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Chapter 1. 
INTRODUCTION 

OVERVIEW 


About this document 

This document describes the Common User Functions. It 
contains general information about the Common User 
Functions, as well as a detailed description of each 
individual Common User Function. 


Intended audience 

This document is intended for programmers writing 
software in DASL on the RMS operating system. 

It contains code segments of DASL programs that reference 
the NOSL I/O package, the D$IO package, and the RMS 
operating system. 
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OVERVIEW 


How this document is organized 

This document is divided into ten chapters. Chapters 3 
through 10 contain detailed descriptions of the Common 
User Functions which have been categorized by 
programming function. 


Chapter 

Content 

1 

Introduction to the Common User Functions. 

2 

Procedures for including a Common User Function 
into your DASL program. 

3 

Memory allocation Common User Functions. 

4 

Character and string Common User Functions. 

5 

Input/output Common User Functions. 

6 

Message handling Common User Functions. 

7 

List processing Common User Functions. 

8 

Program structuring Common User Functions. 

9 

Scheduler Common User Functions. 

10 

Miscellaneous Common User Functions. 
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INTRODUCTION TO COMMON USER FUNCTIONS 


Introduction 

You can probably remember an occasion when you needed 
to write code that another programmer had already 
written. But because that code was undocumented or 
buried deep within an unfamiliar program, you probably 
ended up writing your own version. 

In response to this problem, a collection of useful, 
efficient, well written functions have been assembled and 
packaged as the Common User Functions. 


Definition of a Common User Function 
A Common User Function is 

• a macro, 

• a function, or 

• a set of related macros and functions 

specifically designed for solving a DASL programming 
problem. 


Designed to run efficiently 

Each Common User Function has been designed to run 
efficiently. Several functions take advantage of specific 
machine instructions to attain maximum efficiency. 
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INTRODUCTION TO COMMON USER FUNCTIONS 


Common User Functions are also called "CUFs" 

The Common User Functions are commonly referred to by 
the acronym, "CUFs”. "CUFs” will be used throughout 
the remainder of this document. 


Anatomy of a CUF 

Each CUF may contain one or more of the following DASL 
elements: 


DASL Element 

Description 

Type definition 

Type definitions define a variable 
structure needed by a CUF. 

Variable 

Variables are flags, counters, 
structures, etc... that 

• must be declared by you prior to 
calling a CUF, or 

• are provided for you to examine the 
status or result of a CUF. 

Macro 

Macros 

• interface you to a CUF function, or 

• are changed into a problem solving 
statement or group of statements. 


Note: Macros that are called like 
functions will be referred to as 
functions throughout the remainder of 
this document. 

Function 

Functions solve part or all of a 
common programming problem. 
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INTRODUCTION TO COMMON USER FUNCTIONS 


Examples of CUFs 

Some examples of CUFs are 

• a macro that determines the maximum of two values, 

• a function that makes a copy of a string, and 

• a set of functions and macros that dynamically allocate 
memory. 
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Chapter 2. 
INCLUDING A CUF 

OVERVIEW 


Introduction 

This chapter contains the procedures for including a CUF 
into your DASL program. 


Overview of the procedure 

The procedures for including a CUF are outlined in the 
following table. A description of each procedure in this 
table is included in this chapter. 


Task 

Action 

1 

Include the CUF definition file into your DASL 
program. 

2 

Declare any variables needed by the CUF in your 
DASL text. 

B 

Initialize any variables needed by the CUF in 
your DASL text. 

n 

Edit the CUF function call into your DASL text. 

B 

Include the CUF relocatable library in your LINK 
directives. 
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INCLUDE CUF DEFINITION FILE 


Introduction 

Each individual CUF has a corresponding CUF definition 
file which must be included in the INCLUDE portion of your 
DASL program. 


Task 

Action 

1 

Include the CUF definition file into your DASL 
program. 


Description of a CUF definition file 

A CUF definition file is a text file that contains definitions 
and external references that are needed to reference the 
CUF. Its filename is made from the name of the CUF with a 
"/DEFS" extension. 

Example : The $SCAN CUF filename is $SCAN/DEFS. 


Example 


The following program segment includes the $SCAN CUF 
definition file. 


INCLUDE(D$INC) 

INCLUDE(DSRMS) 

INCLUDE($SCAN/DEFS) /* Include $SCAN CUF */ 

: (rest of the program) 
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DECLARE CUF VARIABLES 


Introduction 

Several CUFs require you to declare variables of certain 
types to be passed as parameters to the CUF functions or 
returned as results of the CUF functions. 


Task 

Action 

2 

Declare any variables needed by the CUF in your 
DASL text. 


Example 


The $SCAN function of the $SCAN CUF requires you to pass 
the address of the first character of a string, a character to 
scan for in the string, and the number of characters to scan 
in the string. The following program segment declares the 
variables needed for the call to $SCAN. 


INCLUDE(D$INC) 

INCLUDE(D$RMS) 

INCLUDE($SCAN/DEFS) /* Include $SCAN CUF */ 

ENTRY MAIN () := 

VAR n BYTE; 

string [80] CHAR; 
scanChar CHAR; 

{ 

scanChar := 

n := n$read(n$WSIn, &string[0], SIZEOF string); 

IF $SCAN(&string[0], scanChar, n) = n THEN 
error('Scan character not found.'); 

: (rest of the program) 
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INITIALIZE CUF VARIABLES 


Introduction 

Several CUFs require you to initialize variables prior to 
calling the functions. 


Task 

Action 

3 

Initialize any variables needed by the CUF in 
your DASL text. 


Example 


The $SCAN function requires you to pass in an initialized 
string, character, and number. The following program 
segment initializes these variables. 


INCLUDE(DSINC) 

INCLUDE(DSRMS) 

INCLUDE($SCAN/DEFS) /* Include $SCAN CUF */ 

ENTRY MAIN () := 

VAR n BYTE; 

string [80] CHAR; 
scanChar CHAR; 

{ 

scanChar := ; 

n := n$read(n$WSIn, &stringf0], SIZEOF string); 

IF $SCAN(&string[0], scanChar, n) = n THEN 
error('Scan character not found.'); 

: (rest of the program) 
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CALL CUF FUNCTION 


Introduction 

After you have declared and initialized any variables 
required by the CUF function, the function call must be 
edited into your DASL text. 


Task 

Action 

4 

Edit the CUF function call into your DASL text. 


Example 


The following program segment calls the $SCAN function of 
the $ SCAN CUF. 


INCLUDE(D$INC) 

INCLUDE(D$RMS) 

INCLUDE($SCAN/DEFS) /* Include $SCAN CUF */ 

ENTRY MAIN () := 

VAR n BYTE; 

string [80] CHAR; 
scanChar CHAR; 

{ 

scanChar := ' 

n := n$read(n$WSIn, &string[0], SIZEOF string); 

IF $SCAN(&string[0], scanChar, n) = n THEN 
error(’Scan character not found.'); 

: (rest of the program) 
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INCLUDE CUF RELOCATABLE LIBRARY 


Introduction 

All of the individual CUF’s relocatable object files are 
combined into a single relocatable library which must be 
included by the LIBRARY directive in LINK. 


Task 

Action 

5 

Include the CUF relocatable library in your LINK 
directives. 


Selecting the correct CUFs library 

There are several copies of the CUFs library that support 
three of the DATAPOINT instruction sets. Use this table to 
select the proper CUFs library for your instruction set. 


If you are writing for the... 

then use... 

5500 instruction set 

SCUFS/REL5 

6600 instruction set 

$CUFS/REL 

16000 instruction set 

$CUFS/RL16 
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INCLUDE CUF RELOCATABLE LIBRARY 


Example 


If you had selected $CUFS/REL, your LINK directives might 
look like this: 


SEGMENT MYPROG 
INCLUDE DASLASM 
INCLUDE D$LIB.D$START 
LIBRARY N$ 

LIBRARY $CUFS 
LIBRARY D$LIB 
LIBRARY RMSUFRS 
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Chapter 3. 

MEMORY ALLOCATION CUFS 

OVERVIEW 


Introduction 

This chapter contains a description of the two memory 
allocation CUFs, $ ALLOC and $ BUDDY. 

The memory allocation CUFs obtain memory from RMS that 
can be dynamically allocated and deallocated by your 
program. The memory maintained by the memory 
allocation CUFs is referred to as the ’’memory pool”. 


Selecting a CUF 

Use the following table to select a memory allocation CUF. 


In addition to allocating 
memory, if you want to ... 

then use... 

page 

• find additional memory when the 
memory pool has been exhausted, 

• add memory to the memory pool, or 

• add the unused memory above the top 
of your program to the memory pool 

SALLOC. 

3-2 

• allocate aligned memory, up to 32K 
at a time, or 

• use the same memory allocation CUF 
as the NOSL I/O package 

$BUDDY. 
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$ALLOC 


Introduction 

The $ALLOC CUF is a dynamic memory allocation package 
with supporting functions that can be used to 

• find additional memory when the memory pool has been 
exhausted, 

• add memory to the memory pool, and 

• add the unused memory above the top of your program 
to the memory pool. 


SALLOC and RMS 

The $ALLOC CUF allocates memory from RMS and manages 
the memory internally in a memory pool. The $ALLOC CUF 
does not provide a facility to return the memory to RMS. 
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$ALLOC 


$ALLOC variables and functions 

Use the following table to select a $ ALLOC variable or 
function. 


If you want to ... 

then see. . . 

page 

determine the amount of memory 
allocated up till now 

SMAXALLOC. 

3-3 

allocate memory from the memory pool 

SALLOC, or 
$NEW. 

3-4 

3-5 

return memory to the memory pool 

$FREE, or 
SDISPOSE. 

3-6 

3-7 

allocate memory from RMS 

SMOREMEM. 

3-8 

add memory to the memory pool 

SMEMFREE. 

3-10 

add high memory to the memory pool 




$MAXALLOC variable 

$MAXALLOC is declared as part of the $ALLOC CUF and is 
available for you to examine. 


Variable Definition 

Description 

SMAXALLOC UNSIGNED; 

Maximum amount of dynamic memory 
allocated from the memory pool up 
to now. 


Chap ter 3 . 


MEMORY ALLOCATION CUFS 


3-3 
























$ALLOC 


$ALLOC function 

$ ALLOC allocates memory from the memory pool. 


Function Syntax 

Input 

Output 

SALLOC ( 




size UNSIGNED 

Number of bytes 
allocate. 

to 


) a BYTE; 


Points to the 
allocated memory. 
Note: Equals NIL 
if there's no more 
memory available. 


Example : 


function () := 

VAR ptr a BYTE; 

{ 

ptr ;= $ALLOC(4096); 
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$ALLOC 


$NEW function 

$NEW allocates enough memory for whatever the input 
variable is pointing to. 


Function Syntax 

Input 

Output 

$NEW ( 

ptr a Anything 

Pointer to any 

Points to the 


type. 

allocated variable 

); 


of that type. 

Note: Equals NIL 
if there’s no more 
memory available. 


Example : 


function () := 

VAR ptr a SSFENT; 

{ 

$NEW(ptr); 
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$ALLOC 


$FREE function 

$FREE returns memory to the memory pool. 


Function Syntax 

Input 

Output 

SFREE ( 



ptr a BYTE 

Pointer to the first byte of 
memory to return. 

Note; Must point to memory that 



was previously allocated by 


): 

$ALL0C or $NEW. 



Example : 


function () := 

VAR ptr a BYTE; 

{ 

ptr := $ALLOC(4096); 
$FREE(ptr); 
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$ALLOC 


$DI3P0SE function 

$DISPOSE returns the memory used by whatever the input 
variable is pointing to back to the memory pool. 


Function Syntax 

Input 

Output 

SDISPOSE ( 

ptr a Anything 

); 

Pointer to a variable of any 
type. 

Note: Must point to a 
variable that was previously 
allocated by $ALLOC or $NEW. 



Example : 


function () := 

VAR ptr a SSFENT; 

{ 

SNEW(ptr); 
$DISPOSE(ptr); 
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$ALLOC 


$MOREMEM function 

$MOREMEM allocates additional memory from RMS when 
the memory pool has been exhausted. $MOREMEM is 

• automatically called by $ALLOC and $FREE when the 
memory pool has been exhausted and 

• automatically calls $MEMFREE if it is successful in 
allocating additional memory. 


Function Syntax 

Input 

Output 

SMOREMEM ( 

size UNSIGNED 

) BOOLEAN; 

Amount of memory 
needed. 



TRUE if additional 
memory was found 
FALSE otherwise. 


Note : There are benefits for replacing this function with 
your own version. Two replacements are described below. 

• Define $MOREMEM to terminate program execution with 
an error message if it cannot get additional memory. 

You can avoid having to check each $ALLOC call 

for a NIL return by defining $MOREMEM this way. 

• Define $MOREMEM to $MEMFREE any buffers or tables 
that are no longer used by your program to the memory 
pool and return TRUE. 
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5ALL0C 


fcMOREMEM function (continued) 

Example : The following program segment replaces the CUF 
$MOREMEM function with the first of the replacement 
functions described on the previous page. 

Note : $MOREMEM must be declared "ENTRY". 


ENTRY $MOREMEN (size UNSIGNED) BOOLEAN ;= 

VAR msn BYTE; 

i, n BYTE; 
psk BYTE; 

f 

RESULT := FALSE; 
msn := 0; 
i ;= 0; 

n := (size + 4095) / 4096; 

LOOP { 

WHILE i < n & msn < 16; 

IF $MEMKEY(msn++ « 4, &psk) && D$CFLAG 
& $ERRC.$CODE = 1 THEN i++ 

ELSE i ;= 0; 

}; 

IF i = n THEN { 
i ;= 0; 

LOOP { 

WHILE i < n 

& ~($$MEMGET(&psk) && D$CFLAG) 

& ~($MEMMAP(—msn « 4, psk) && D$CFLAG); 
i++; 

}; 

IF i = n THEN { 

$MEMFREE(<a BYTE>(msn « 12), 4096 * n); 
RESULT ;= TRUE; 

}; 

}; 

IF ~ RESULT THEN { 

display('FATAL ERROR: No more memory.’); 
$ERROR(); 

}; 
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$MEMFREE function 

$MEMFREE adds memory to the memory pool. 

Note : You don’t need to call this function unless 

• you are setting up your own memory pool, or 

• you replaced the $MOREMEM function with your own 
version and are giving additional memory to $ALLOC. 


Function Syntax 

Input 


Output 

SMEMFREE ( 




ptr a BYTE, 

Address of the first byte in 
memory to add to the memory 
pool. 


size UNSIGNED 

); 

Number of bytes to add to 
memory pool. 

the 



Example : 


function () := 

VAR STATIC memPool [500] BYTE; 

{ 

$MEMFREE(&memPool[0], SIZEOF memPool); 
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$ALLOC 


$TOPFREE function 

$TOPFREE adds the unused memory above the top of your 
program to the memory pool. 

You must define $LOADTOP as the ’’next available byte” 
address label of the SEGMENT directive in the linkage 
phase of the DASL compile process. 

Example : Your LINK directives might look like 
this: 


SEGMENT MY PROG,,$LOADTOP 
INCLUDE DASLASM 
INCLUDE D$LIB.D$START 
LIBRARY N$ 

LIBRARY $CUFS 
LIBRARY D$LIB 
LIBRARY RMSUFRS 


Function Syntax 

Input 

Output 

STOPFREE ( 

): 




Example : 


function () := 
{ 

$TOPFREE(); 
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$BUDDY 


Introduction 

The $BUDDY CUF is a dynamic memory allocation package 
that allocates aligned memory based upon the amount of 
memory requested from the memory pool. 


Aligned memory 

Memory allocated from $ BUDDY is aligned on the nearest 
2" boundary, where 2" is the lowest power of 2 greater 
than or equal to the amount of memory requested. For 
example: 

• a request for 256 bytes will return memory aligned on a 
page boundary that may be used for a $PFDB buffer, and 

• a request for 4096 bytes will return memory aligned on a 
sector boundary which can be mapped in and out of 
logical space. 


$BUDDY and RMS 

The $ BUDDY CUF allocates memory from RMS and manages 
the memory internally in a memory pool. The $ BUDDY CUF 
does not provide a facility to return the memory to RMS. 
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$BUDDY functions 

Use the following table to select a $ BUDDY function. 


If you want to... 

then see... 

page 

allocate memory from memory pool 

Salloc, or 
$new. 

3-13 

3-14 

return memory to memory pool 

$free, or 
Sdispose. 

3-15 

3-16 


$alloc function 

$ alloc allocates aligned memory from the memory pool. 


Function Syntax 

Input 

Output 

Salloc ( 

size UNSIGNED 

) a BYTE; 

Number of bytes to 
allocate. 



Points to the 
allocated memory. 
Note: Equals NIL 
if there’s no more 
memory available. 


Example : 


function () := 

VAR ptr a BYTE; 

{ 

ptr ;= $alloc(4096); 
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$new function 

$new allocates aligned memory for whatever type the 
input variable is pointing to. 


Function Syntax 

Input 

Output 

$new ( 

ptr a Anything 

Pointer to any 

Points to the 


type. 

allocated variable 

); 


of that type. 

Note: Equals NIL 
if there's no more 
memory available. 


Example : 


function () := 

VAR ptr a $SFENT; 

1 

$new(ptr); 
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$free function 

$free returns memory to the memory pool. 


Function Syntax 

Input 

Output 

$free ( 



ptr a BYTE, 

Pointer to the first byte of 
memory to return. 

Note: Must point to memory 
that was previously allocated 
by $alloc or $new. 


size UNSIGNED 

Number of bytes of memory to 
return to the memory pool. 

Note: The number of bytes must 
be the same as the number 


); 

originally allocated. 



Example : 


function () := 

VAR ptr a BYTE; 

{ 

ptr := $alloc(4096); 
$free(ptr, 4096); 
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$dispose function 

$ dispose returns the memory used by whatever the input 
variable is pointing to back to the memory pool. 


Function Syntax 

Input 

Output 

$dispose ( 

ptr a Anything 

Pointer to a variable of any 


); 

type. 

Note: Must point to a 
variable that was previously 
allocated by $alloc or $new. 



Example : 


function () := 

VAR ptr a $SFENT; 

{ 

$new(ptr); 
$dispose(ptr); 
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Chapter 4. 

CHARACTER AND STRING CUFS 

OVERVIEW 


Introduction 

This chapter describes the character and string handling 
CUFs. 

The character and string handling CUFs are used to search, 
compare, convert, and clear characters and strings. 


Selecting a CUF 

Use the the following to select a character and string 
handling CUF. 


If you want to ... 

then use ... 

page 

• perform a byte-by-byte translation 
on an input string, or 

• look for the first occurrence in a 
string for one of a number of 
possible characters 

SCONVERT. 

1 

initialize a table, array, etc... 
with a certain character 

$FILL. 

■ 

compare two strings for a mismatch 

SMATCH. 


scan a string for a character 

$SCAN. 

EB 

search a string for an instance of 
another string 

$SEARCH. 

4-10 

define, compare, or copy strings 
that are part of a type that also 
includes the string length 

SSTRING or 
$STRCMP. 

■ 


Chapter 4. 


CHARACTER AND STRING CUFS 


4-1 














$CONVERT 


Introduction 

The $ CONVERT CUF is a single function which performs a 
byte-by-byte translation on the input string until 

• the termination character is found in the string, or 

• the maximum number of characters to translate is 
reached. 


Byte-by-byte translation process 

The byte-by-byte translation process is shown in the 
following diagram. 


$CONVERT... 


Example 


takes the byte value of 
the character in the 
input string, 


c d 


L 


1 


byte value 
of "a" is 
0141 


uses that value as an 
index into the 
translation table that 
you provide, 


stops if the character 
from the translation 
table is equal to the 
termination character, 


0 

0 

0 


0 


r 

0 

I 



0 0 0 


11 3 

4 4 7 

1 2 7 


example 
? termination 
character 
is 


and replaces the string 
character with the 
character from the 
translation table. 


s b c 


d 


the "a" in 
the string 
is replaced 
by an "s". 
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$CONVERT function 

$CONVERT performs a byte-by-byte translation on the 
input string looking for a termination character. 


Function Syntax 

Input 

Output 

SCONVERT ( 

str a CHAR, 

Address of the 
first character of 
a string. 


len UNSIGNED, 

Number of 
characters to 
translate in the 
string. 


tablePtr a [256] CHAR, 

Address of a 
translation table. 
Note: The 
translation table 
must be page 
aligned for the 
55/6600 instruction 
set. 


term CHAR 

Terminate 

translation if this 
character is found 
in the string. 

Note: This 
character cannot be 
0 on the 55/6600 
instruction set. 


) UNSIGNED; 


Number of 
characters 
translated. 
Note: Does 
not include 
"term" if 
f ound. 


Chapter 4. CHARACTER AND STRING CUFS 


4-3 







$CONVERT 


$CONVERT function (continued) 

Example : The following program segment demonstrates 
how to use the $ CONVERT CUF to look for the first 
occurrence of any of several characters in an input string. 
Note how the translation table is initialized to translate all 
characters except V into themselves. $CONVERT will 
terminate if it finds either V or V in the input string. 


function () := 

VAR trans a [256] CHAR; 
i BYTE; 

STATIC str [4] CHAR := 'abed'; 

{ 

$new(trans); /* allocate aligned trans table */ 
i := 0; 

LOOP { 

transAti] := i; 

WHILE i-H- ~= 255; 

1 ; 

transA['b' ] := f c’ ; 

i ;= $CONVERT(&str[0], 4, trans, ’c’); 
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$FILL 


Introduction 

The $FILL CUF is a single function which initializes 
memory. 


$FILL function 


$FILL initializes strings, arrays, tables, structures, etc... to 
a specified character. 


Function Syntax 

Input 

Output 

SFILL ( 



p a BYTE, 

Address of the first byte to 
initialize. 


size UNSIGNED, 

Number of bytes to initialize. 


filler BYTE 
); 

Value to store into each byte. 



Example : 


function () := 

VAR a [1000] CHAR; 

{ 

$FILL(&af0], SIZEOF a , ’O'); 
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Introduction 

The $ MATCH CUF is a single function which compares two 
strings for a mismatch. 


$MATCH function 

$ MATCH compares two strings for a mismatch. 


Function Syntax 

Input 

Output 

$MATCH ( 

p a BYTE, 

Address of the first 
byte of the first 
string to compare. 


q a BYTE, 

Address of the first 
byte of the second 
string to compare. 


len UNSIGNED 

Number of bytes to 
compare. 


) UNSIGNED; 


Number of bytes 
that match. 


Example : 


function () := 

VAR s [256] CHAR; 

STATIC p [8] CHAR := 'PASSWORD'; 

{ 

n$read(n$WSIn, &s[0], SIZEOF p-fl); 

IF $MATCH(&p[0], SiSlOl, 8) = 8 THEN matched() ; 
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$SCAN 


Introduction 

The $SCAN CUF is a character scanning package which 
scans 

• forward or 

• backward 

through a string for a character. 


$SCAN functions 

Use the following table to select a $SCAN function. 


If you want to.. . 



scan forward for character 

$ SCAN. 

4-8 | 

scan backward for character 


oa 
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$SCAN 


$SCAN function 

$SCAN scans forward through a string for a character. 


Function Syntax 

Input 

Output 

$SCAN ( 

str a CHAR, 

Address of the 
first character in 
the input string. 


key CHAR, 

Character to look 
for in the string. 


len UNSIGNED 

Number of 
characters in the 
string to scan. 


) UNSIGNED; 


Number of 
that were 
before the 
was found. 

characters 

skipped 

character 


Example : 


function () := 

VAR n BYTE; 

s [80] CHAR; 

{ 

n := n$read(n$WSIn, &s[0], SIZEOF s); 
IF $SCAN(&sf0], '?’, n) = n THEN 
error(’Invalid input string'); 
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$SCAN 


$SCANR function 

$SCANR scans backward through a string for a character. 


Function Syntax 

Input 

Output 

$SCANR ( 

str a CHAR, 

Address of the 
last character in 
the input string. 


key CHAR, 

Character to look 
for in the string. 


len UNSIGNED 

Number of 
characters in the 
string to scan. 


) UNSIGNED; 


Number of characters 
that were skipped 
before the character 
was found. 


Example : 


function () := 

VAR n BYTE; 

s [80] CHAR; 

{ 

n := n$read(n$WSIn, &s[0], SIZEOF s); 
n := $SCANR(&s[n-lI, ’A', n); 
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$SEARCH 


Introduction 

The $ SEARCH CUF is a string searching package which 
searches 

• forward or 

• backward 

through a string for an instance of another string. 


$SEARCH functions 

Use the following table to select a $ SEARCH function. 


If you want to... 

then see ... 

page 

search forward for string 

SSEARCH. 

4-11 

search backward for string 

SSEARCHR. 

4-12 
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$SEARCH 


$SEARCH function 

$ SEARCH searches forward through a string for an instance 
of another string. 


Function Syntax 

Input 

Output 

$SEARCH ( 

key a CHAR, 

Address of the first 
character of the 
string you are 
searching for. 


keyLen UNSIGNED, 

Number of characters 
in the string you are 
searching for. 


str a CHAR, 

Address of the first 
character of the 
string you are 
searching. 


strLen UNSIGNED 

Number of characters 
in the string you are 
searching. 


) UNSIGNED; 


Number of 
characters 
that were 
skipped before 
the string was 
found. 


Example : 


function () := 

VAR n BYTE; 

s [80] CHAR; 

STATIC key [] CHAR := 'HELLO'; 

{ 

n := n$read(n$WSIn, &s[0], SIZE0F s); 
n := $SEARCH(&key[0], SIZEOF key, &s[0], n-1); 
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$SEARCHR function 

$SEARCHR searches backward through a string for an 
instance of another string. 


Function Syntax 

Input 

Output 

SSEARCHR ( 

key a CHAR, 

Address of the last 
character of the 
string you are 
searching for. 


keyLen UNSIGNED, 

Number of characters 
in the string you are 
searching for. 


str a CHAR, 

Address of the last 
character of the 
string you are 
searching. 


strLen UNSIGNED 

Number of characters 
in the string you are 
searching. 


) UNSIGNED; 


Number of 
characters 
that were 
skipped before 
the string was 
found. 


Example : 


function () := 

VAR n BYTE; 

s [80] CHAR; 

STATIC key [] CHAR := 'HELLO 1 ; 

{ 

n := n$read(n$WSIn, &s[0], SIZEOF s); 
n := $SEARCHR(&key[4l, SIZEOF key , &s[n-ll, n); 
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$STRING 


Introduction 

The $STRING CUF is a string manipulation package which 
contains a macro and functions to 

• initialize, 

• compare, and 

• copy 

strings which are declared as part of a type, $ String, which 
also includes their length. 


$STRING types, macros, and functions 

Use the following table to select a $ STRING type, macro, or 
function. 


If you want to... 

then see... 

page 

define a string variable 

SString. 

4-14 

initialize a SString variable 

$str. 

4-14 

check two strings for equality 

SstringEqual. 

4-16 

copy a string 

SstringCopy. 

4-16 
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$STRING 


SString type 


$ String is defined as follows: 


Type Definition 

Description 

TYPDEF SString STRUCT { 
ptr a CHAR; 

len UNSIGNED; 

} ; 

Pointer to a string. 

Length of the pointed string. 


$str macro 


$str is a macro which generates an initializer for variables 
of type $String. 


Function Syntax 

Input 

Output 

Sstr ( 

str [any size] CHAR 

) SString; 

Any character 
string. 



A SString 
initializer 
containing the 
string and the 
string length. 


Example : 


function () := 

VAR STATIC s $String := $str('I am a string’); 


4-14 


DASL USER'S GUIDE 


50807-01 





$STRING 


$stringEqual function 

$stringEqual compares two strings, described by their 
respective $ String types, to determine if they are equal. 


Function Syntax 

Input 

Output 

$stringEqual ( 



strl a $String, 

Address of the 
first string 
descriptor. 


str2 a $String 

Address of the 
second string 
descriptor. 


) BOOLEAN; 


TRUE if the 
strings are equal 
in content and 
length. FALSE 
otherwise. 


Example : 


function () := 

VAR STATIC key $String := $str('PASSWORD' ) ; 
st $String; 
s [80] CHAR; 

{ 

st.ptr := &s[0] ; 

st.len := n$read(n$WSIn, st.ptr, SIZEOF s) - 1; 
IF $stringEqual(&key, &st) THEN equal(); 
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SstringCopy function 

$stringCopy copies one string, described by the $ String 
type, into another. 


Function Syntax 

Input 

Output 

SstringCopy ( 

from a $String, 

Address of the 
source string 
descriptor. 


to a SString, 

Address of the 
destination 
string 
descriptor. 

Describes the 
copied string. 
Note: No copy is 
done if source 
is larger than 
the destination. 

leftover a SString 

May be NIL. If 
not it is used 
as an output 
variable. 

Describes the 
unused area in 
the resulting 
destination 
string, tOA. 

) BOOLEAN; 


TRUE if source 
fits into 
destination. 

FALSE otherwise. 


Example : 


function () := 

VAR STATIC sourcel SString := $str('Source') ; 

STATIC source2 $String := $str(' String’); 
s [80] CHAR; 

STATIC dest $String := $str(s); 
leftover $String; 

{ 

IF $stringCopy(&sourcel, Sidest, &lef tOver) 

& $stringCopy(&source2 , Sclef tOver, NIL) THEN 
concatenatedStrings(); 
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$STRCMP 


Introduction 

The $STRCMP CUF is a single function which compares two 
strings that are described by the $ String type. 

Note : $String is declared in the $STRING CUF. 


$STRCMP definition file 

The $STRCMP definition file must be included after the 
$STRING definition file. 

Example : Your DASL include directives might look 
like this: 


INCLUDE(D$INC) 
INCLUDE(D$RMS) 
INCLUDE($STRING/DEFS) 
INCLUDE($STRCMP/DEFS) 

: (rest of the program) 


STRING 
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$strCmp function 

$strCmp compares two strings described by their 
respective $ String types. 


Function Syntax 

Input 

Output 

SstrCmp ( 

slP a $String, 

Address of the 
first string 
descriptor. 


s2P a $String 

Address of the 
second string 
descriptor. 


) SET ( 

$strL, 


The first string is 
less than the second. 

$strS, 


The first string is 
an initial substring 
of the second. 

$strE f 


The strings are equal. 

$strB, 


The second string is 
an initial substring 
of the first. 

$strG 

); 


The first string is 
greater than the 
second. 
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SstrCmp function (continued) 

Example : The following program segment compares two 
strings, key and st, and tests the $strE flag which will be 
set if the two strings are equivalent in length and content. 


function () := 

VAR STATIC key $String := $str('PASSWORD’) ; 
st SString; 
s [80] CHAR; 

{ 

st.ptr := &s[0]; 

st.len := n$read(n$WSIn, st.ptr, SIZEOF s) - 1; 
IF $strCmp(&key, &st) && $strE THEN equalQ; 


STRING 
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Chapter 5. 

INPUT/OUTPUT CUFS 

OVERVIEW 


Introduction 

This chapter describes the input/output CUFs. 

The input/output CUFs are used to handle general keyboard 
and file I/O. 


Selecting a CUF 

Use the following table to determine which input/output 
CUF to use. 


If you want to ... 

then use... 

page 

allocate a page aligned buffer and 
a $PFDB that describes the buffer 

$BUFFER. 


open or create a binary or text file 
under D$I0 and automatically 
allocate buffers and supporting file 
structures 

SEZOPEN. 

5-6 

read a text file forward and 
backward and insert and delete lines 

$SEQFH. 

5-22 

obtain a single translated character 
from the keyboard 

SGETKEYCH. 

5-13 

obtain a single untranslated 
character from the keyboard 

$KEYCH. 

5-17 
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$BUFFER 


Introduction 

The $ BUFFER CUF is a file I/O package that allocates and 
deallocates a page aligned buffer and a $PFDB (with 
$PFDBBUFs if necessary) that describe the buffer. 

Note : $BUFFER uses the $ BUDDY CUF for its memory 
allocation and deallocation. 


$BUFFER types and functions 

Use the following table to select a $ BUFFER type or 
function. 


If you want to ... 

then see... 

page 

declare a buffer descriptor 

$BufDesc. 

5-3 

allocate a page aligned buffer 

SalocBuf. 

5-4 

free a buffer allocated by $alocBuf 

$freeBuf. 

5-5 
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$BufDesc type 

$BufDesc is defined as follows: 


Type Definition 

Description 

TYPDEF SBufDesc STRUCT { 


addr a BYTE; 

Points to the allocated page 
aligned buffer. 

size UNSIGNED; 

Size of allocated buffer. 

Note: Always a multiple of 


256. 

pfdbP a $PFDB; 

}; 

Points to the allocated $PFDB. 
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$BUFFER 


$alocBuf function 

$alocBuf allocates a page aligned buffer and a $PFDB that 
describes the buffer. 


Function Syntax 

Input 

Output 

SalocBuf ( 

bDP a $BufDesc, 

Address of a 
buffer descriptor. 

Stores the 
address, size, 
and $PFDB of the 
buffer in bDPA. 

size UNSIGNED 

Number of bytes to 
allocate for the 
file buffer. 

Note: Number is 
rounded up to a 
multiple of 256. 


) BOOLEAN; 


TRUE if able to 
allocate buffer. 
FALSE otherwise. 


Example : 


function () := 

VAR bufDesc SBufDesc; 

{ 

IF $alocBuf(&bufDesc, 4-096) THEN allocatedQ; 
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SfreeBuf function 

$freeBuf frees the buffer and $PFDB allocated by $alocBuf 
and returns it to the memory manager, $ BUDDY. 


Function Syntax 

Input 

Output 

SfreeBuf ( 

bDP a SBufDesc 

); 

Address of the buffer 
descriptor which describes 
the buffer and SPFDB to 
return. 

Note: Must point to a 
buffer descriptor that was 
previously set by SaiocBuf. 



Example : 


function () := 

VAR bufDesc SBufDesc; 

{ 

IF SaiocBuf(&bufDesc, 4096) THEN allocated(); 
$freeBuf(&bufDesc); 
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$EZOPEN 


Introduction 

The $EZOPEN CUF is an interface to the D$IO package that 
manages its own buffer allocation and tables. $EZOPEN 
contains functions for both binary and text files that can 

• open a file for reading, 

• prepare a file for writing, and 

• close a file. 


$EZOPEN functions 

Use the following table to select a $EZOPEN function. 


If you want to ... 

then see... 

page 

open a text file for reading 

StextRead. 

El 

open a text file for writing 



close a text file 

StextClose. 

B 

open a binary file for reading 


5-10 

open a binary file for writing 


Bfl 

close a binary file 

SbinaryClose. 

B9 
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$EZOPEN 


$textRead function 

$textRead opens a D$IO text file for reading. 

Note : $textRead will terminate through $ERMSG if the file 
does not exist. 


Function Syntax 

Input 

Output 

StextRead ( 

sfent a $SFENT 

Address of 
file entry 
of the file 
be opened. 

the 

table 

to 


) a D$FILET; 


Address of the 

D$I0 text file. 
Note: NIL if it 
can't allocate 
memory. 


Example : 


function () := 

VAR inFileET $SFENT; 

inFile a D$FILET; 

{ 

inFileET.$SFTSFN := 'IN 
inFileET.$SFTNAM := 'MYFILE 
inFileET.$SFTEXT := 'TEXT'; 
inFileET.$SFTENV := 'W '; , 

inFile := $textRead(&inFileET); 

IF inFile = NIL THEN 

display('Insufficient memory'); 
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$textPrep function 

$textPrep creates a D$IO text file for writing. 
Note : $textPrep will recreate an existing file. 


Function Syntax 

Input 

Output 

StextPrep ( 

sfent a $SFENT 

Address of 
file entry 
of the file 
be created. 

the 

table 

to 


) a DSFILET; 


Address of the 

D$IO text file. 
Note: NIL if it 
it can’t allocate 
memory. 


Example : 


function () := 

VAR outFileET $SFENT; 

outFile a DSFILET; 

{ 

outFileET.$SFTSFN := 'OUT 
outFileET.SSFTNAM := 'MYFILE 
outFileET.$SFTEXT := ’TEXT’; 
outFileET.$SFTENV := 'W ’; 

outFile := $textPrep(&outFileET); 
IF outFile = NIL THEN 

display('Insufficient memory'); 
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StextClose function 

$textClose closes a D$IO text file and deallocates the 
memory allocated by $textRead or $textPrep. 


Function Syntax 

Input 

Output 

StextClose ( 

filet a D$FILET 

); 

Pointer to an open D$I0 text 
file. 

Note: Must point to a file 
that was opened by StextRead 
or StextPrep. 



Example : 


function () := 

VAR outFileET $SFENT; 

outFile a D$FILET; 

{ 

outFileET.SSFTSFN := ’OUT ' ; 

outFileET.SSFTNAM := ’MYFILE 
outFileET.$SFTEXT := ’TEXT’; 
outFileET.SSFTENV := 'W ’ ; 

outFile := $textPrep(&outFileET); 
$textClose(outFile); 
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$EZOPEN 


$binaryRead function 

$binaryRead opens a D$IO binary file for reading. 

Note : $binaryRead will terminate through $ERMSG if the 
file does not exist. 


Function Syntax 

Input 

Output 

SbinaryRead ( 

sfent a $SFENT 

Address of 
file entry 
of the file 
be opened. 

the 

table 

to 


) a D$FILEB; 


Address of the 

D$IO binary file. 
Note: NIL if it 
it can't allocate 
memory. 


Example : 


function () := 

VAR inFileET $SFENT; 

inFile a D$FILEB; 

{ 

inFileET.$SFTSFN := 'IN ’; 

inFileET.$SFTNAM := 'MYFILE 
inFileET.SSFTEXT := 'REL ' ; 
inFileET.$SFTENV := 'W 
inFile := $binaryRead(&inFileET); 
IF inFile = NIL THEN 

display(’Insufficient memory’); 
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$EZOPEN 


SbinaryPrep function 

$binaryPrep creates a D$IO binary file for writing. 
Note : $binaryPrep will recreate an existing file. 


Function Syntax 

Input 

Output 

$binaryPrep ( 



sfent a $SFENT, 

Address of the 
file entry table 
of the file to 
be created. 


format BYTE 

RMS file format. 
Example: $FFMTBIN 


) a DSFILEB; 


Address of the 

D$IO binary file. 
Note: NIL if it 
it can't allocate 
memory. 


Example : 


function () := 

VAR outFileET $SFENT; 

outFile a DSFILEB; 

{ 

outFileET.$SFTSFN := 'IN 

outFileET.SSFTNAM := 'MYFILE 

outFileET.SSFTEXT := 'REL 

outFileET.$SFTENV := 'W ' ; 

outFile := $binaryPrep(&outFileET, $FFMTL55); 

IF outFile = NIL THEN 

display('Insufficient memory'); 
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SbinaryClose function 

$binaryClose closes a D$IO binary file and deallocates the 
memory allocated by $binaryRead or $binaryPrep. 


Function Syntax 

Input 

Output 

SbinaryClose ( 



filet a D$FILEB 

Pointer to an open D$I0 
binary file. 

Note: Must point to a file 
that was opened by 


); 

SbinaryRead or SbinaryPrep. 



Example : 


function () := 

VAR outFileET $SFENT; 

outFile a D$FILEB; 

{ 

outFileET.SSFTSFN := 'IN ’ ; 

outFileET.$SFTNAM := 'MYFILE '; 

outFileET.$SFTEXT := 'REL 
outFileET.$SFTENV := 'W 

outFile := $binaryPrep(&outFileET, $FFMTL55); 
$binaryClose(outFile); 
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Introduction 

The $GETKEYCH CUF is a general keyboard I/O package 
that contains 

• definitions for the cursor control keypad, 

• a function to obtain one translated character from the 
keyboard, and 

• a function to turn shift inversion on or off. 


$GETKEYCH definitions and functions 

Use the following table to select a $GETKEYCH definition 
or function. 


If you want to. . . 


page 

use the translated numeric keypad 
definitions 

Cursor 
control 
keypad 
definitions. 

5-14 

obtain one translated character from 
the keyboard 

SGETKEYCH. 

5-15 

turn shift inversion on or off 

SGETKEYCHI. 

5-16 
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SGETKEYCH 


Cursor control keypad definitions 

The following definitions are the translated definitions of 
the numeric keypad into the cursor control keypad by 
$GETKEYCH. 


aboveLeft 

arrowUp 

aboveRight 

7 

8 

9 


arrowLeft 

arrowMiddle 

arrowRight 

4 

5 

6 


be lowLeft 

arrowDown 

belowRight 

3 

2 

1 


wideZero 

dot 

0 



Two other definitions are also provided. They are 

• numberPad , which is the first value in the cursor control 
keypad definitions, and 

• afterNumberPad, which is the value after the cursor 
control keypad definitions. 

Example : The following example shows how these 
definitions can be used in a program segment. 


IF numberPad <= char & char < afterNumberPad THEN 
CASE char { 

arrowUp : moveUp(); 
arrowLeft : moveLeft() ; 
arrowRight : moveRight(); 
arrowDown : moveDown(); 


ELSE notCursorControl() ; 
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$GETKEYCH function 

$GETKEYCH obtains one translated character from the 
keyboard. The character is not echoed on the screen. 


Function Syntax 

Input 

Output 

SGETKEYCH ( 
h BYTE, 

Horizontal position to 
obtain the character. 

Note: Valid inputs are 

0 to 79. 


v BYTE 

Vertical position to 
obtain the character. 

Note: Valid inputs are 

0 to 23 on a 24 line 

screen. 


) CHAR; 




Example : 


function () := 

VAR char CHAR; 

{ 

char := $GETKEYCH(15, 20); 
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$GETKEYCHI function 

$GETKEYCHI turns shift inversion on or off. 


Function Syntax 

Input 

Output 

SGETKEYCHI ( 

invert BOOLEAN 

); 

TRUE turns shift inversion 
on, FALSE turns shift 
inversion off. 



Example : 


function () := 

{ 

$GETKEYCHI(TRUE); 
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$KEYCH 


Introduction 

The $KEYCH CUF is a general keyboard I/O package that 
contains functions to 

• obtain one untranslated character from the keyboard, 

• restore the keyboard translate pointer, 

• allow or inhibit control of the cursor, and 

• set a keyin timeout value. 


$KEYCH functions 

Use the following table to select a $KEYCH function. 


If you want to... 

then see... 

page 

obtain one untranslated character 
from the keyboard 

SKEYCH. 

5-18 

restore the keyboard translation 
table pointer 

SKEYCHR. 

5-19 

allow or inhibit control of the 

cursor 

SKEYCHE. 

5-20 

set keyin timeout value 

SKEYCHT. 

5-21 
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$KEYCH function 

$KEYCH obtains one untranslated character from the 
keyboard. The character is not echoed on the screen. 

Note : This function changes the keyboard translation table 
pointer. Call $KEYCHR to restore this pointer. 


Function Syntax 

Input 

Output 

$KEYCH ( 

horz BYTE, 

Horizontal position to 
obtain the character. 
Note: Valid inputs are 

0 to 79. 


vert BYTE 

Vertical position to 
obtain the character. 
Note: Valid inputs are 

-12 to 11 on a 24 line 

screen. 


char a CHAR 


Stores the 
untranslated 
character in 
char a . 

SWSTIMEO if 
time out 
occurred. 

) D$CC0DE; 


$WSI0 error 
if one occurs. 


Example : 


function () := 

VAR char CHAR; 

{ 

IF $KEYCH(0, -12, &char) && D$CFLAG THEN $ERMSG() ; 
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$KEYCHR function 

$KEYCHR restores the keyboard translation table pointer 
to the value it had before $KEYCH was called the first 
time. This function must be called before calling any keyin 
routines that expect translated characters. Example : 
$WSIO, $GETKEYCH, etc... 


Function Syntax 

Input 

Output 

$KEYCHR ( 

) D$CCODE; 


$WSIO error if one occurs. 


Example : 


function () := 

VAR char CHAR; 

{ 

IF $KEYCH(0, >12, &char) && D$CFLAG THEN $ERMSG(); 
IF $KEYCHR() && D$CFLAG THEN $ERMSG() ; 
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$KEYCHE function 

$KEYCHE allows or inhibits $KEYCH from controlling the 
cursor. 


Function Syntax 

Input 

Output 

SKEYCHE ( 

cursOn BOOLEAN 

); 

TRUE enables $KEYCH to turn 
the cursor on and off, FALSE 
inhibits $KEYCH from 
controlling the cursor. 



Example : 


function () := 

{ 

$KEYCHE(TRUE); 


/ 
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$KEYCHT function 

$KEYCHT sets the keyin timeout value in seconds. 

Note : The keyin timeout value will default to $ FOREVER if 
this function is not called. 


Function Syntax 

Input 

Output 

SKEYCHT ( 

timeOut BYTE 

Number of seconds to wait for 


); 

keyin character. 

Note: $FOREVER means not to 
time out. 



Example : 


function () := 

{ 

$KEYCHT(10); 
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Introduction 

The $SEQFH CUF is a sequential text file handling package 
that allows reading a text file forwards and backwards 
while inserting and deleting lines. 


Input file 


The sequential file handler manages the text file through 
three individual windows: 


• The records above the current 
sequential record, 


• the current sequential record, and 


• the records below the current 
sequential record. 


Your view of the input file is through the current 
sequential record window. 
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$SEQFH 


How the windows work 

This diagram illustrates the three window file management: 
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$SEQFH 


$SEQFH types and functions 

Use the following table to select a $SEQFH type or 
function. 


If you want to ... 

then see... 

page 

declare a sequential file 

SFHSIPT. 

5-25 

initialize the sequential file 
handler 

Ssfhlnit. 

5-26 

get a record from the above window 

SsfhGetA. 

5-27 

write the character string into the 
above window 

$sfhPutA. 

5-29 

get a record from the below window 

SsfhGetB. 

5-30 

write the character string into the 
below window 

$sfhPutB. 

5-32 

force the records in the above and 
below windows to be written to the 
output file 

$sfhQuit. 

5-33 

release all memory sectors used by 
the sequential file handler 

$sfhRmem. 

5-34 
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$SEQFH 


SFH$IPT type 

SFH$IPT is defined as follows: 


Type Definition 

Description 

TYPDEF SFHSIPT STRUCT { 
SFH$IMNS BYTE; 

Maximum number of sectors to 
allocate in 4K quantities. 

SFHSIEFP LONG; 

Input end-of-file pointer. 

SFHSIIN a SPFDB; 

Address of the open input file 
SPFDB. 

SFHSIOUT a SPFDB; 

Address of the open output 
file SPFDB. 

SFHSISCR a SPFDB; 

Address of the open scratch 
file SPFDB. 

SFHSIASM BYTE; 

Mapped sector number, MSN, of 
a 4K sector of memory to be 
used for buffering the portion 
of the input file above the 
current sequential record. 

SFHSIBSM BYTE; 

Mapped sector number, MSN, of 
a 4K sector of memory to be 
used for buffering the portion 
of the input file below the 
current sequential record. 

SFHSIGET a DSCALLF; 

Address of a memory allocation 
routine. 

Example: MEMGETS 

SFHSIREL a DSCALLF; 

} ; 

Address of a memory 
deallocation routine. 

Example: MEMRELS 
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$SEQFH 


$sfhlnit function 

$sfhlnit initializes the sequential file handler. 


Function Syntax 

Input 

Output 

Ssfhlnit ( 

sfhPtr a SFH$IPT 

) D$CCODE; 

Address of an 
initialized 
sequential file 
descriptor. 



D$CFLAG if there 
is insufficient 
memory available. 


Example : 


function () := 

VAR sfhlpt SFH$IPT; 


sfhlpt.SFHSIMNS 
sfhlpt.SFHSIEFP 


:= 64; 


/* 256 K max */ 


sfhlpt.SFH$IIN 
sfhlpt.SFH$IOUT 
sfhlpt.SFH$ISCR 
sfhlpt.SFH$IASM 
sfhlpt.SFHSIBSM 
sfhlpt.SFH$IGET 
sfhlpt.SFH$IREL 


D$GET24(&inOpenPt.$OTFLEN) « 
|| inOpenPt.SOTFEOFB; 

&inPfdb ; 


&outPfdb; 

&scratchPfdb 
016«4; 

017<<4; 

&MEMGETS; 

&MEMREL$; 

IF $sfhlnit(&sfhlpt) && D$CFLAG THEN 

error('Insufficient memory available 1 ) 


8 


/* 016-0167777 */ 
/* 017-0177777 */ 
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SsfhGetA function 

$sfhGetA gets a record from the above window into the 
current sequential record buffer. 


Function Syntax 

Input 

Output 

SsfhGetA ( 

destPtr aa CHAR, 

Address of a 
pointer to 
the last 
position in 
the current 
sequential 
record 
buffer. 

Note: This 

Pointer destPtrA points 
to the byte before the 
first byte stored in the 
current sequential record 
buffer. 


buffer must 
include space 
for two 

SLEORs. 




len BYTE 

Size of the 
buffer. 


) D$CCODE; 


D$CFLAG 

D$ZFLAG 

Function 

Result 



FALSE 

— 

No error. 



TRUE 

FALSE 

Maximum 
length 
overflow. 




TRUE 

Beginning 
of file. 
One $LEOR 
obtained. 
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$sfhGetA function (continued) 

Example : In the following program segment, $sfhGetA 
gets (or pops) the last record from the above window and 
stores it into the buffer. 


function () := 

VAR DEFINE(bufSize, 250) 

buffer [bufSize] CHAR; 
ptr a CHAR; 
flag DSCCODE; 

{ 

ptr := &buffer[bufSize-1 ] ; 
flag ;= $sfhGetA(&ptr, bufSize); 

IF flag && DSCFLAG THEN { 

IF flag && D$ZFLAG THEN display('Top of file.’) 
ELSE error('Input record too large'); 

} 

ELSE { 

n$write(n$WSOut, ptr+1, &buffer[bufSize]-ptr) ; 
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SsfhPutA function 

$sfhPutA writes the character string into the above 
window. 


Function Syntax 

Input 

Output 

SsfhPutA ( 

source a CHAR 

); 

Address of the first character 
in the line storage buffer 
terminated by a $LEOR. 



Example : In the following program segment, $sfhPutA 
puts (or pushes) the record in the buffer into the above 
window. 


function () := 

VAR DEFINE(bufSize, 250) 

buffer [bufSize] CHAR; 
ptr a CHAR; 
n BYTE; 

{ 

ptr := &buffer[0]; 
n := n$read(n$WSIn, ptr, bufSize); 
buffer[n-l] := $LEOR; 

$sfhPutA(ptr); 
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$sfhGetB function 

$sfhGetB gets a record from the below window. 


Function Syntax 

Input 

Output 

SsfhGetB ( 

destPtr aa CHAR, 

Address of a 
pointer to 
the first 
position in 
the current 
sequential 
record 
buffer. 

Note: This 
buffer must 
include space 
for one 
$LEOR. 

Pointer destPtrA points 
to the byte after the 
last byte stored in the 
current sequential record 
buffer. 

len BYTE 

Size of the 
buffer. 


) DSCCODE; 


D$CFLAG 

D$ZFLAG 

Function 

Result 



FALSE 

— 

No error. 



TRUE 

FALSE 

Maximum 

length 

overflow. 




TRUE 

End of 
file. 

One $LE0R 
obtained. 
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SsfhGetB function (continued) 

Example : In the following program segment, $sfhGetB 
gets (or pops) the first record from the below window and 
stores it into the buffer. 


function () := 

VAR DEFINE(bufSize, 250) 

buffer [bufSize] CHAR; 
ptr a CHAR; 
flag D$CC0DE; 

{ 

ptr := &buffer[0]; 

flag := $sfhGetB(&ptr, bufSize); 

IF flag && D$CFLAG THEN { 

IF flag && DSZFLAG THEN display('End of file.’) 
ELSE error('Input record too large'); 

1 

ELSE { 

n$write(n$WSOut, &buffer[0], ptr-buffer[0] ) ; 
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$sfhPutB function 

$sfhPutB writes the character string into the below window. 


Function Syntax 

Input 

Output 

SsfhPutB ( 



source a CHAR, 

Address of the $LEOR 
following the last character 
in the line storage buffer. 


len BYTE 

Number of characters from the 
line storage buffer to write. 
Note: Including space for the 
$LE0R. 


)? 




Example : In the following program segment, $sfhPutB 
puts (or pushes) the record in the buffer into the below 
window. ^ 


function () := 

VAR DEFINE(bufSize, 250) 

buffer [bufSize] CHAR; 
n BYTE; 

{ 

n := n$read(n$WSIn, &buffer[0], bufSize); 
buffertn-1] := $LE0R; 
$sfhPutB(&bufferln-ll, n); 
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SsfhQuit function 

$sfhQuit forces the records in the above and below 
windows to be written to the output file and puts an EOF 
mark into the output file. 


Function Syntax 

Input 

Output 

SsfhQuit ( 

eofPtr a LONG 

Address of a LONG 

Stores the output 


variable. 

file EOF pointer in 

); 

i 

eofPtrA. 


Example : 


function () := 

VAR eof LONG; 

{ 

$sfhQuit(&eof); 
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$sfhRmem function 

$sfhRmem releases all memory sectors used by the 
sequential file handling routines. 


Function Syntax 

Input 

Output 

SsfhRmem ( 

); 




Example : 


function () := 

VAR eof LONG; 

{ 

$sfhQuit(&eof); 
$sfhRmem(); 
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Chapter 6. 

MESSAGE HANDLING CUFS 

OVERVIEW 


Introduction 

This chapter describes the message handling CUFs. 

The message handling CUFs are used to handle message 
I/O. 


Selecting a CUF 

Use the following table to determine which message 
handling CUF to use. 


If you want to ... 

then use... 

page 

• open a specific message file, 

• access specific messages, or 

• access messages sequentially 

$MSG. 


access specific message members from 
D$I0 D$WRITE statements 

$MSGIO. 

6-6 
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$MSG 


Introduction 

The $MSG CUF is a message I/O package that can 

• open a command file and search for a message member, 

• copy a message from the message member into 
memory, and 

• get sequential messages from the message member. 


$MSG functions 

Use the following table to select a $MSG function. 


If you want to ... 

then see ... 

page 

open a message member 

SMSGOPEN. 

6-3 

get a specific message 

SMSGGET. 

6-4 

get the next message 

SMSGNEXT. 

6-5 
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$MSG 


$MSGOPEN function 

$MSGOPEN looks up a message member in the specified 
file. 


Function Syntax 

Input 

Output 

SMSGOPEN ( 



pfdbPtr a $PFDB, 

Address of a command 
file $PFDB. 

Note: If the $PFDB 
$FAVID is a $NOADR, 
it will open the 
executing command 
file. 


memNamePtr a $LNAMET 

Address of the name 
of the message 
member. 


) D$CCODE; 


D$CFLAG 
if I/O 

error . 


Example : 


function () := 

VAR bufDesc SBufDesc; /* $BUFFER CUF */ 

STATIC mName $LNAMET := 'MESSAGE 

{ 

IF SalocBuf (StbufDesc, 256) THEN { 

bufDesc.pfdbPA.$PFVID := SPCRFVUP ; 

IF $MSGOPEN(bufDesc.pfdbP, &mName) 

&& D$CFLAG THEN $ERMSG(); 

} 

ELSE error('Insufficient memory'); 
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$MSG 


$MSGGET function 

$MSGGET copies a specified message from the message 
member into memory. 


Function Syntax 

Input 

Output 

SMSGGET ( 

msgNr UNSIGNED, 

Number of the message 
to get. 


msgPtr a CHAR, 

Address of the first 
character in the area 
to store the message. 

Points to 
the message 
terminated by 
a $ES. 

msgMaxLen BYTE 

Maximum space 
available to store the 
message. 


) D$CC0DE; 


D$ZFLAG if 
message not 
found. 

D$CFLAG if 

I/O error. 


Example : 


function () := 

VAR flag D$CCODE; 

message [80] CHAR; 

{ 

flag := $MSGGET(10, &message[Oj, SIZEOF message); 

IF flag && D$CFLAG THEN $ERMSG(); 

IF flag && D$ZFLAG THEN error('Message not found’); 
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$MSGNEXT function 

$MSGNEXT copies the next sequential message from the 
message member into memory. 


Function Syntax 

Input 

Output 

SMSGNEXT ( 

msgPtr a CHAR, 

Address of the first 
character in the area 
to store the message. 

Points to 
the message 
terminated by 
a $ES. 

msgMaxLen BYTE 

Maximum space 
available to store the 
message. 


) D$CCODE; 


D$CFLAG if 

I/O error. 


Example : 


function () := 

VAR i, n BYTE; 

message [80] CHAR; 

{ 

i := 0; 

LOOP { 

IF $MSGNEXT(&message[0], SIZEOF message) 

&& D$CFLAG THEN $ERMSG() ; 
n := $SCAN(&message[0], $ES, SIZEOF message); 
n$format(n$WSOut, S(message, n), LN); 

WHILE ++i < 10; 

} ; 
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SMSGIO 


Introduction 

The $MSGIO CUF is used to access a message member 
through D$IO. 


Open the message member first 

The $MSGIO CUF uses the $MSG CUF to access the message 
member. You must open the message member with 
$MSGOPEN before using the $MSGIO CUF. 


The "M" phrase type 

$MSGIO adds the ,f M" or message phrase type to the D$IO 
D$ WRITE phrases. 

The "M" instructs the D$IO driver that a message number 
will follow as the next parameter. This message number is 
used to look up the corresponding message in the message 
member. The corresponding message is written to the 
output device. 

Syntax for the "M" phrase is 
M, Cmessage number> 
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The "M" phrase type (continued) 


Example : 


pfdb $PFDB := { $NOADR, {0,0}, 1,0, 1, 

{ { $N0PSK, (<UNSIGNED>&D$BUF1) >>8 } } 

} ; 

function () := 

VAR STATIC mName $LNAMET := 'MESSAGE ' ; 

{ 

IF $MSGOPEN(&pfdb, &mName) && D$CFLAG THEN $ERMSG( ) ; 
D$WRITE(&D$DSP, S, 'Message # 24 is ' , M, 24, LN) ; 
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Chapter 7. 

LIST PROCESSING CUFS 

OVERVIEW 


Introduction 

This chapter describes the list processing CUFs. 

The list processing CUFs are used to process linked lists 
and character queues. 


Selecting a CUF 

Use the following table to determine which list processing 
CUF to use. 


If you want to... 

then use.. . 

page 

manipulate data with doubly linked 
lists 

SLINKS. 

H 

buffer characters on a queue 

SQUEUE. 

mm 
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SLINKS 


Introduction 

The $LINKS CUF is a doubly linked list manipulation 
package. 


$LINKS types and functions 

Use the following table to select a $ LINKS type or function. 


If you want to... 

then see... 

page 

declare a linked list descriptor 

SListHeader. 

7-3 

insert a node into the linked list 

SLLINS. 

7-4 

delete a node from the linked list 

SLLDEL. 

7-5 
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Slinks 


SListHeader type 

$ListHeader is defined as follows: 


Type Definition 

Description 

TYPDEF SListHeader STRUCT { 


f a SListHeader; 

Forward pointer to the next 


linked list node. 

r a SListHeader; 

Reverse pointer to the 

} ; 

previous linked list node. 


Example : Linked lists are not useful unless they contain 
more data than the links. This example uses the linked list 
type as a field in a larger structure. 


TYPDEF NameList STRUCT { 
links $ListHeader; 
name [30] CHAR; 
address [50] CHAR; 
id UNSIGNED; 

} ; 
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SLINKS 


SLLINS function 

$LLINS inserts a new node onto the linked list. 


Function Syntax 

Input 


Output 

SLLINS ( 




new a SListHeader, 

Address of the 
to insert onto 
linked list. 

new node 
the 


after a SListHeader 

); 

Address of the node in 
the linked list to 
insert the new node 
after. 



Example : 


start NameList; 

function () := 

VAR node NameList; 

{ 

$LLINS(&node.links, &start.links); 
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$LLDEL function 

$LLDEL deletes a node from the linked list. 


Function Syntax 

Input 

Output 

SLLDEL ( 

old a SListHeader 

) a SListHeader; 

Address of the 
node to remove 
from the linked 
list. 



Address of the 
node removed 
from the linked 
list. 


Example : 


function (pNode a SListHeader) := 

{ 

$LLDEL(pNode); 
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$QUEUE 


Introduction 

The $QUEUE CUF is a set of functions for handling a 
circular character queue buffer. 


$QUEUE types and functions 

Use the following table to select a $QUEUE type or 
function. 


If you want to. . . 

then see. . . 

page 

declare a character queue 
descriptor 

$Queue. 

7-7 

initialize a queue descriptor 

$initQueue. 

7-8 

add a character to the queue 

SaddQueue. 

7-9 

delete a character from the queue 

$remQueue. 

7-10 

determine the number of characters 
in the queue 

SsizeQueue. 

7-11 

determine the number of character 
places left in the queue 

SslacklnQueue. 

7-12 

determine if the queue is full 

SisQueueFull. 

7-13 

determine if the queue is empty 

SisQueueEmpty. 

7-14 
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$QUEUE 


$Queue type 

$Queue is defined as follows: 


Type Definition 

Description 

TYPDEF SQueue STRUCT { 
start a CHAR; 

Pointer to the starting boundary 
of the queue. 

end a CHAR; 

Pointer to the ending boundary 
of the queue. 

first a CHAR; 

Pointer to the first character 
in the active queue. 

after a CHAR; 

1 ; 

Pointer to the character after 
the last character in the active 
queue. 
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$QUEUE 


$initQueue function 

$initQueue initializes a queue descriptor. 


Function Syntax 

Input 

Output 

SinitQueue ( 



q a Queue, 

Address of a queue 

Initialized queue 


descriptor. 

descriptor with 
starting and ending 
boundaries, and 
active queue 
pointers. 

buff a CHAR, 

Address of the 
first character 
in the character 
buffer to be used 
as the queue. 

Note: The buffer 
should be one byte 
larger than what 
you are intending 
to use. 


len UNSIGNED 

); 

Number of 
characters in the 
buffer to be used 
as the queue. 



Example : 


function () := 

VAR queue $Queue; 

buffer [1000] CHAR; 

{ 

$initQueue(&queue , &buffer[0], SIZEOF buffer); 
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$QUEUE 


$addQueue function 

$addQueue adds a character into the queue. 


Function Syntax 

Input 

Output 

SaddQueue ( 



q a SQueue, 

Address of the 
queue descriptor. 


c CHAR 

Character to be 
added to the queue. 


) BOOLEAN; 


TRUE if successful 
in adding the 
character to the 
queue. FALSE 
otherwise. 


Example : 


function (pQueue a SQueue) := 

VAR letter CHAR; 

{ 

letter := 'A'; 

LOOP { 

IF ~ $addQueue(pQueue, letter) THEN 
error(’No more room in the queue'); 
WHILE letter-H- < 'Z'; 

} ; 
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$QUEUE 


$remQueue function 

$remQueue removes the first character from the queue. 


Function Syntax 

Input 

Output 

SremQueue ( 
q a $Queue, 

Address of the 
queue descriptor. 


cPtr a CHAR 

Address of a 
character. 

Stores the 
character removed 
from the queue into 
cPtrA. 

) BOOLEAN; 


TRUE if successful 
in removing the 
character from the 
queue. FALSE 
otherwise. 


Example : 


function (pQueue a SQueue) := 

VAR ch CHAR; 

{ 

IF $remQueue(pQueue, &ch) THEN 

n$format(n$WSOut, ’Removed ’ , C(ch), LN) ; 
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$QUEUE 


$sizeQueue function 

$sizeQueue determines the number of characters in the 
queue. 


Function Syntax 

Input 

Output 

SsizeQueue ( 
q a $Queue 

Address of the 
queue descriptor. 


) UNSIGNED; 


Number 
in the 

of characters 
queue. 


Example : 


function (pQueue a $Queue) := 

{ 

n$format(n$WSOut, D( $sizeQueue(pQueue) ), 
' characters in the queue’, LN) ; 
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$QUEUE 


$slacklnQueue function 

$slackInQueue determines the number of available 
character places left in the queue. 


Function Syntax 

Input 

Output 

$slackInQueue ( 
q a $Queue 

) UNSIGNED; 

Address of the 
queue descriptor. 



Number of available 
character places 
left in the queue. 


Example : 


function (pQueue a SQueue) := 

{ 

n$format(n$WSOut, D( $slackInQueue(pQueue) ), 
' available characters in the queue', LN); 
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$QUEUE 


SisQueueFull function 

$isQueueFull determines whether the queue buffer space 
has been exhausted. 


Function Syntax 

Input 

Output 

SisQueueFull ( 



q a SQueue 

Address of the 
queue descriptor. 


) BOOLEAN; 


TRUE if the queue 
buffer is full. 



FALSE otherwise. 


Example : 


function (pQueue a SQueue) := 

{ 

IF $isQueueFull(pQueue) THEN 
display('Queue is full'); 
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$QUEUE 


SisQueueEmpty function 

$isQueueEmpty determines whether the queue is empty. 


Function Syntax 

Input 

Output 

SisQueueEmpty ( 
q a $Queue; 

) BOOLEAN; 

Address of the 
queue descriptor. 



TRUE if the queue 
does not contain 
any entries. FALSE 
otherwise. 


Example : 


function (pQueue a SQueue) := 

{ 

IF $isQueueEmpty(pQueue) THEN 
display('Queue is empty'); 
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Chapter 8. 

PROGRAM STRUCTURING CUFS 

OVERVIEW 


Introduction 

This chapter describes the program structuring CUFs. 

The program structuring CUFs are used to conditionally 
compile code, simulate bit fields, etc... 


Selecting a CUF 

Use the following table to determine which message 
handling CUF to use. 


If you want to... 

then use... 

page 

exit your program with an internal 
error message written with D$IO if 
certain conditions in your program 
are not TRUE 


8-2 

exit your program with an internal 
error message written with N0SL if 
certain conditions in your program 
are not TRUE 

Sassert. 

8-3 

jump between two functions 

$CATCH. 

8-4 

simulate bit fields 

$FIELD. 

OO 

i 

00 

simulate C language "for" loops 

$F0R. 

8-15 

selectively compile parts of your 
program 

IFINC. 

8-19 
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$ASSERT 


Introduction 

The $ASSERT CUF is a single function which checks 
conditions in a program that should be TRUE. If a "FALSE 
assertion" occurs, $ASSERT will terminate the program 
with an internal error message through D$IO. 


$ASSERT function 

$ASSERT displays an internal error message and exits 
through $ ERROR on a false boolean input. 


Function Syntax 

Input 

Output 

SASSERT ( 



flag BOOLEAN, 

Boolean condition to 
examine. 


msg [any size] CHAR 

Message to display 
before terminating 


); 

program execution. 



Example : 


function () := 

{ 

$ASSERT(ptr ~= NIL, 'Pointer cannot be NIL'); 
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$assert 


Introduction 

The $assert CUF is a single function which checks 
conditions in a program that should be TRUE. If a ’’FALSE 
assertion” occurs, $assert will terminate the program with 
an internal error message through the NOSL I/O package. 


$assert function 

$ assert displays an internal error message and exits 
through $ ERROR on a false boolean input. 


Function Syntax 

Input 

Output 

Sassert ( 



flag BOOLEAN, 

Boolean condition to 
examine. 


msg [any size] CHAR 

Message to display 
before terminating 


); 

program execution. 



Example : 


function () := 

{ 

$assert(ptr ~= NIL , 'Pointer cannot be NIL'); 
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$CATCH 


Introduction 

The $CATCH CUF is a machine dependent implementation 
of nonlocal goto’s. 

Note : If you need to use this CUF, you may be doing 
something wrong. 


SCATCH types and functions 

Use the following table to select a $ CATCH type or 
function. 


If you want to... 

then see ... 

page 

declare a goto location descriptor 

$ SAVE. 

8-5 

set a return address for a nonlocal 
goto 

$CATCH. 

8-5 

jump to the address in the location 
descriptor 

$THROW. 
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$CATCH 


$SAVE type 

The $SAVE type is nonportable and its contents need not be 
examined by your program. 

$SAVE is defined as follows: 


Type Definition 

Description 

TYPDEF $SAVE STRUCT { 
retPC a BYTE; 

prevSP a BYTE; 

1 ; 

Return address to exit to. 

Saved stack pointer. 


$CATCH function 

$CATCH sets a return address for a nonlocal goto. 


Function Syntax 

Input 

Output 

$CATCH ( 

p a $SAVE 

Address of an 
address and state 
descriptor. 

Initialized address 
and state descriptor 
with current 
position info. 

) BOOLEAN; 


Always returns TRUE. 
Note: If STHROW is 
called with this 
address descriptor, 
program control 
returns to this 

SCATCH call with a 
FALSE result. 
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$CATCH 


$THROW function 

$THROW jumps to the specified address. 


Function Syntax 

Input 

Output 

STHROW ( 

p a $SAVE 

) BOOLEAN; 

Address of the 
address and state 
descriptor to goto. 



Always FALSE. 

Note: This value 
actually gets set 
into $CATCH so that 
FALSE is returned 
by $CATCH after a 
STHROW. 
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$CATCH 


Example of the $CATCH CUF 

In the following example, $CATCH [1] is executed. It will 
set throwAddr [2] with the return address, and return a 
TRUE boolean condition. This causes functionO to be 
called. If $THROW [3] is called, it will return through the 
$CATCH [1] call, returning a FALSE boolean condition 
which will result in $ERROR() [4] being called. 


throwAddr $SAVE; [2] 

function () := 

VAR s [80] CHAR; 
n BYTE; 

{ 

n := n$read(n$WSIn, &s[0], SIZEOF s); 

IF s(01 = ' ' THEN $THROW(&throwAddr); [3] 

: (rest of the function) 

} ; 

ENTRY MAIN () := 

{ 

IF $CAICH(&throwAddr) THEN function() [1] 

ELSE $ERR0R(); [4] 

} ; 
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$FIELD 


Introduction 

The $ FIELD CUF is a bit field simulation package which 
enables you to set up a named mask to define a bit or a 
set of adjacent bits in a single scalar to be a separate field. 


Bit field numbering 

The bit positions in a scalar are numbered starting at zero 
from least to most significant. 

The following diagram shows the bit numbers of a byte. 


7 

6 

5 

4 

3 

2 

1 

0 


$FIELD macros and functions 

Use the following table to select a $ FIELD macro or 
function. 


If you want to.. . 

then see... 

page 

define a field identifier 

field. 

8-9 

get a field 

fieldGet. 

8-10 

test a field for nonzeros 

fieldTest. 

8-11 

store a value into a field 

fieldStore. 

8-12 

set a field 

fieldSet. 

8-13 

clear a field 

fieldClear. 

8-14 
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$FIELD 


field macro 


field defines an identifier to be a location and width of a 
field within a scalar. 


Function Syntax 

Input 

Output 

field ( 



name Identifier, 

A DASL identifier. 

Note: Be careful not to use 
the same name more than 

once. 


offset BYTE, 

Bit position of the field. 


size BYTE 

> 

Number of bits in the 
field. 



Example : The following program segment defines six 
different bit fields bitO, bitl, ..., bits5to7. All but the last 
field are one bit masks. bits5to7 is a three bit mask. 


function () := 

VAR byte BYTE; 

field(bitO, 0, 1) 
fieldfbitl, 1,1) 
field(bit2, 2, 1) 
field(bit3, 3, 1) 
field(bit4, 4, 1) 
field(bits5to7, 5, 3) 

{ 
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$FIELD 


fieldGet function 

fieldGet gets the field defined by the identifier from a 
DASL scalar. 


Function Syntax 

Input 

Output 

fieldGet ( 



value Scalar, 

DASL scalar that 
contains the 
field. 


name Identifier 

Name of the mask 
that identifies 
the field within 
the scalar. 


) Scalar; 


Contents of the 
field. 


Example : The following program segment gets the high 
order 8 bit field of the integer "i". 


field(highByte, 8, 8) 

function (i INT) := 

VAR fid BYTE; 

{ 

fid := fieldGet(i, highByte); 
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$FIELD 


fieldTest function 

fieldTest tests for nonzeros in a field. 


Function Syntax 

Input 

Output 

fieldTest ( 

value Scalar, 

DASL scalar that 
contains the field 
to evaluate. 


name Identifier 

Name of the mask 
that identifies 
the field within 
the scalar. 


) BOOLEAN; 


TRUE if the value 
of the field is 
nonzero. FALSE 
otherwise. 


Example : 


field(prtFlag, 13, 1) 

function (flags UNSIGNED) := 

{ 

IF fieldTest(flags, prtFlag) THEN printltQ; 
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$FIELD 


fieldStore function 

fieldStore stores a value into a field. 


Function Syntax 

Input 

Output 

fieldStore ( 

valuePtr a Scalar, 

Address of the 
DASL scalar that 
contains the 
field to be 
stored into. 


name Identifier, 

Name of the mask 
that identifies 
the field within 
the scalar. 


value Scalar 

Value to be 
stored into the 
field. 


) Scalar; 


The input DASL 
scalar with the 
updated field. 


Example : 


field(highByte, 8, 8) 

function (i UNSIGNED) := 

{ 

fieldStore(&i, highByte, 0377); 
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$FIELD 


fieldSet function 

fieldSet sets the bits in the field of a scalar to ones. 


Function Syntax 

Input 

Output 

fieldSet ( 

valuePtr a Scalar, 

Address of the 
DASL scalar that 
contains the 
field to be set. 


name Identifier, 

Name of the mask 
that identifies 
the field within 
the scalar. 


) Scalar ; 


The input DASL 
scalar with the 
updated field. 


Example : 


field(prtFlag, 13, 1) 

function (flags UNSIGNED) := 

{ 

fieldSet(&flags, prtFlag ); 
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$FIELD 


fieldClear function 

fieldClear clears the bits in a field to zeros. 


Function Syntax 

Input 

Output 

fieldClear ( 



valuePtr a Scalar, 

Address of the 
DASL scalar that 
contains the 
field to be 
cleared. 


name Identifier, 

Name of the mask 
that identifies 
the field within 
the scalar. 


) Scalar; 


The input DASL 
scalar with the 
updated field. 


Example : 


field(prtFlag, 13, 1) 

function (flags UNSIGNED) := 

{ 

fieldClear(&flags, prtFlag); 


8-14 


DASL USER'S GUIDE 


50807-01 









$FOR 


Introduction 

The $FOR CUF is a set of macros which simulate the C 
language ’’for” statement. 


$FOR macros 

Use the following table to select a $FOR macro. 


If you want to ... 

then see. . . 

page 

begin "for" loop structure 

$f or. 

8-16 

end "for" loop structure 

$next. 

8-16 
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$FOR 


$for macro 


$for designates the beginning of the "for” loop structure. 
It is parameterized with 

• a preloop initialization statement, 

• a conditional exit expression, and 

• an incrementation statement. 


Macro Syntax 
$for ( 

initialization statement, 

termination expression, 

incrementation statement 

); 


Parameter Description 


Statement that will be 
executed prior to the loop 
structure. 


Boolean condition 
expression that will 
terminate execution of the 
loop when it becomes 
FALSE. 


Last statement in the loop 
to be executed. 


$next macro 

$next designates the end of the "for" loop structure. 


Macro Syntax 

Parameter Description 

Snext; 



Statements located between the $next and matching $for 
macros make up the loop body. 
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$FOR 


$FOR loop structure 

A $FOR loop is opened with a $for and closed with a $next. 



Nested $FOR loops 

$FOR loops may be nested within one another. 
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$FOR 


Cautions 


Users of the $FOR loops should be aware that $for...$next 
loops need to be enclosed in braces if they are used where 
a single statement is required. 

Example : 


IF i = 0 THEN { 

$for (i := 0, i < 100, i++); 

n$format(n$WS0ut, D(i), LN); 
$next; 

}; 


Expanded DASL code 

This is an example of the $FOR and the resultant expanded 
DASL code. 


function () := 

VAR i BYTE; 

{ 

$for (i := 0, i < 100 , i++); 

n$format(n$WSOut, D(i), LN); 
$next; 

Which expands to... 


function () := 

VAR i BYTE; 

{ 

i := 0; 

LOOP { 

WHILE i < 100; 

n$format(n$WS0ut, 
i++; 

} ; 


D(i), 


LN) ; 
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IFINC 


Introduction 

The IFINC CUF is a set of macros which enables selective 
compilation of DASL code. 


IFINC definition file 

The IFINC definition file has a ’’/TEXT” extension. 


Example : 


INCLUDE(D$INC) 

INCLUDE(DSRMS) 

INCLUDE(IFINC/TEXT) 

: (rest of the program) 


IFINC macros 

Use the following table to select a IFINC macro. 


If you want to. .. 

then see ... 

page 

begin a decision block 

$if. 

8-20 

designate an alternate decision 
block branch 

Seise. 

8-21 

end a decision block 

Sendif. 

8-21 
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IFINC 


$if macro 


$if designates the beginning of the decision block for 
selective compilation. 

Note : $if must be preceded by "$esc*/". 


Macro Syntax 

Parameter Description 

$esc*/ $if ( 

first characters to compare, 

A sequence of 
characters or defined 
name of the first 
parameter to compare. \ 

second characters to compare 

A sequence of 
characters or defined 
name of the first 

) 

parameter to compare. 


If the two parameters contain exactly the same characters, 
the code immediately following this macro will be 
compiled. 

Note : Blank characters are significant. 
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IFINC 


$else macro 


$else designates the alternate branch of the decision block. 
Note : $else must be preceded by "$esc*/". 


Macro Syntax 

Parameter Description 

$esc*/ $else 



The $else macro serves two purposes: 

• it terminates the condition block that began at the 
matching $if macro, and 

• it designates the beginning of another condition block 
which ends at the matching $endif macro. 


$endif macro 


$endif designates the end of the decision block. 
Note : $endif must be preceded by "$esc*/". 


Macro Syntax 

Parameter Description 

$esc*/ $endif 



Statements located between the $endif and matching $if 
macros make up the decision block body. 
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IFING 


Decision block structure 

A decision block is opened with a $if and closed with a 
$endif. 


$esc*/ $if (parameter 1, parameter2) 

. (DASL code) 

$esc*/ $endif 

The code inside the decision block is compiled if the $if 
parameters are equal. 


Alternate decision branch 

A decision block may contain an alternate decision branch, 
$else. 


$esc*/ $if (parameter!., parameter2) 

(DASL code) 

$esc*/ $else 

(DASL code) 

$esc*/ $endif 

The code between the $if and the $else is compiled if the 
$if parameters are equal. Otherwise, the code between the 
$else and the $endif is compiled. 
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IFINC 


Nested decision blocks 

Decision blocks may be nested within one another. 

$esc*/ $if (parameterl, parameter2) 

. (DASL code) 

$esc*/ $if (parameterl, parameter2) 
(DASL code) 

$esc>'</ $endif 
. (DASL code) 

$esc*/ $endif 
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IFINC 


Example 


This is an example of the IFINC CUF. The compiled lines 
are bold faced. 


INCLUDE(D$INC) 

INCLUDE(D$RMS) 

INCLUDE(IFINC/TEXT) 

DEFINE(off,0) 

DEFINE(on,1) 

DEFINE(NOSL,on) /* Set either "on" or "off" */ 

DEFINE(LOGGING,off) /* Set either "on" or "off" */ 

$esc*/ $if(NOSL,on) 

INCLUDE(N$/DEFS) 

$esc*/ Seise 
INCLUDE(D$IO) 

Sesc*/ Sendif 

ENTRY MAIN () := 

{ 

$esc'</ $if(NOSL,on) 

$esc*/ $if(LOGGING,on) 

n$format(n$LogOut, 'NOSL is on, LOGGING is on’, LN) ; 
$esc*/ Seise 

n$format(n$WSOut, ’NOSL is on, LOGGING is off , LN); 

Sesc*/ Sendif 
$esc*/ Seise 

Sesc*/ $if(LOGGING,on) 

D$WRITE(&D$OUT, 'NOSL is off, LOGGING is on', LN); 
$esc*/ Seise 

D$WRITE(&D$DSP, ’NOSL is off, LOGGING is off, LN) ; 

Sesc*/ Sendif 
$esc*/ Sendif 
}; 
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Reserved words 

In addition to $esc, $if, $else, and $endif, the following 
names are DEFINEd in the IFINC CUF and should not be 
used. 

• $cat 

• $push 

• $pop 
. $ifStk 

• $cond 

• $getCond 

• $zap 
. $doIf 
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Chapter 9. 
SCHEDULER CUFS 

OVERVIEW 


Introduction 

This chapter describes the scheduler CUFs. 

The scheduler CUFs are used to schedule multiple 
programs running in a single RMS task. 


Scheduler layers 

The scheduler has been broken up into three CUFS in order 
to separate the actual scheduler from the machine 
dependent and operating system dependent functions. 

The separate parts of the scheduler are layered as 
illustrated in the following diagram. 


$SWITCH 

machine dependent, 

coroutine switching 

package - 

page 9-2 $SCHED 

- multiple threading 

scheduler 


page 9-13 


$RMSIDLE 

operating system 
dependent, idle 
thread 

page 9-50 
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$SWITCH 


Introduction ( 

The $SWITCH CUF is the machine dependent, coroutine 
switching part of the scheduler. 


What is a coroutine? 

A coroutine, or concurrent routine, is a routine running 
simultaneously with one or more other routines. 

The term "concurrent" is somewhat misleading since the 

coroutines do not actually run simultaneously. Each 

coroutine runs independently until an instruction is given 

to pass execution control to another coroutine. When 

execution control is returned to the originating coroutine, 

it resumes execution at the point it gave up control. All ( 

other coroutines are "asleep" until they are "awakened" by 

the one active coroutine. 

The term "routine" simply means a sequence of 
instructions. The instructions can be part of one or more 
functions. 
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$SWITCH 


$SWITCH classifications, types, variables, and functions 

Use the following table to select a $ SWITCH classification, 
type, variable, or function. 


If you want to . . . 

then see. . . 

page 

declare a function REENTRANT 

REENTRANT. 

9-4 

define the message parameter 
descriptor 

u$Param. 

9-4 

declare a coroutine stack 
descriptor 

SStackDesc. 

9-5 

use the current stack descriptor 

ScoStackDesc. 

9-5 

initialize the program to be a 
coroutine 

Scolnit. 


create a new coroutine 

ScoFork. 

9-7 

switch to another coroutine 

ScoSwitch. 

9-9 

save the state of a coroutine 

ScoSave. 

9-10 

restore the state of a coroutine 

ScoRestore. 

9-11 
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$SWITCH 


REENTRANT function classification 

REENTRANT is a defined name that is available for you to 
use as a function classification. 


Macro Definition 

Description 

DEFINE(REENTRANT,RECURSIVE) 

Function classification 
for functions that initiate 
new coroutines and for 
functions that may be 
suspended in one coroutine 
while another coroutine is 
running. 


Example : 


REENTRANT function () ;= 
{ 


u$Param type 

The u$Param type is a type that must be declared by you. 
It is used for passing messages or variables between 
coroutines. 

Example : If you wanted to pass 100 byte arrays between 
coroutines, you would define u$Param like this: 


TYPDEF u$Param [100] BYTE; 
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$SWITCH 


SStackDesc type 

The $StackDesc type is needed to define variables used by 
the $SWITCH functions. The contents, however, do not 
need to be set or examined by your program. 

$StackDesc is defined as follows: 


Type Definition 

Description 

TYPDEF SStackDesc STRUCT { 
framePtr a SFrame; 

Points to the function stack 
information. 

Note: SFrame type is defined 

stacklst a BYTE; 

} ; 

in the SSWITCH text. You 
will not need to examine 
variables of this type so 
its description has not been 
made available. 

Points to the first byte 
of the stack information. 


ScoStackDesc variable 

$coStackDesc is declared as part of the $SWITCH CUF and 
is available for you to examine. 


Variable Definition 

Description 

ScoStackDesc a SStackDesc; 

Pointer to the stack 
descriptor of the currently 
active coroutine. 
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$SWITCH 


$colnit function 

$coInit initializes the running program to be a separate 
coroutine. 

Note : This function must be called prior to all other calls to 
the coroutine functions. It should also be called prior to 
any calls to REENTRANT or RECURSIVE functions. 


Function Syntax 

Input 

Output 

Scolnit ( 



stackDesc a SStackDesc, 

Address of a 

Initialized 


stack 

descriptor 


descriptor. 

with 

information 
about the 
stack. 

stack a BYTE, 

Address of the 
first byte of 
the stack 
storage area. 


len UNSIGNED 

Length of the 
stack storage 



area. 


); 




Example : 


routine!. SStackDesc; 
stackl 1500] BYTE; 

function () := 

{ 

$coInit(&routinel , &stackl[0 ], SIZEOF stackl); 
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$SWITCH 


$coFork function 

$coFork creates a new coroutine. 

• The newly created coroutine begins executing from the 
statement following the $coFork. 

• $coFork must be called from within a REENTRANT 
function that is defined to return a pointer to a u$Param. 

• The newly created coroutine must never return from 
the function which called $coFork or a fatal error will 
occur. Processing may be terminated by switching to 
another coroutine. See $coSwitch for further details. 

• The coroutine that calls $coFork falls asleep. If 
execution control is passed back to this coroutine, it 
resumes execution as if it was returning from the 
function that called $coFork. It does not execute the 
remaining code in the function following the $coFork. 


Function Syntax 

Input 

Output 

$coFork ( 

stackDesc a $StackDesc, 

Address of a 
stack 

descriptor. 

Initialized 

descriptor 

with 

information 
about the 
created 
coroutine. 

stack a BYTE, 

Address of the 
first byte of 
the stack 
storage area. 


len UNSIGNED 

); 

Length of the 
stack storage 
area. 
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$SWITCH 


ScoFork function (continued) 

Example : The following segment of code calls the $coFork 
function. 


TYPDEF u$Param BYTE; 

routine2 SStackDesc; 
stack2 [5001 BYTE; 

REENTRANT function () a u$Param := 

{ 

$coFork(&routine2, &stack2[0], SIZEOF stack2); 
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$SWITCH 


$coSwitch function 

$coSwitch passes execution control from one coroutine to 
another. The input parameter, params, will be the RESULT 
of the function that wakes up in the resumed coroutine. 


Function Syntax 

Input 

Output 

$coSwitch ( 

stackDesc a SStackDesc, 

Address of the 
stack 

descriptor to 
switch to. 


params a u$Params 

Address of a 
parameter you 
are passing 
into the 
coroutine you 
are switching 
to. 


) a u$Params; 


Pointer to a 
parameter 
passed back to 
this coroutine 
when it resumes 
execution. 


Example : 


TYPDEF u$Param BYTE; 

routine2 SStackDesc; 
stack2 [500] BYTE; 

REENTRANT function () a u$Param := 

{ 

$coFork(&routine2, &stack2[0], SIZEOF stack2); 
functionl(); 
function2(); 

$coSwitch(&routinel, NIL); 
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$SWITCH 


ScoSave function 

$coSave saves the stack information of the current 
coroutine. 

$coSave and $coRestore are lower level functions used by 
$coSwitch. You will probably not need to call these 
functions directly. 


Function Syntax 

Input 

Output 

ScoSave ( 

); 




Example : 


function () := 

{ f 

$coSave(); 
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SSWITCH 


$coRestore function 

$coRestore restores the stack information which 

• causes the executing coroutine to go to sleep, and 

• causes the coroutine described by stackDesc to resume 
execution. 

Note : $coRestore must be called from within a REENTRANT 
function. The restored coroutine does not actually 
resume execution until the REENTRANT function returns. 

The function may also specify a return parameter for 
passing information between the coroutines. RESULT 
should be assigned after the $coRestore. 

$coSave and $coRestore are lower level functions used by 
$coSwitch. You will probably not need to call these 
functions directly. 


Function Syntax 

Input 

Output 

ScoRestore ( 

stackDesc a SStackDesc, 

); 

Address of the 
stack descriptor of 
the coroutine to 
resume execution. 



Example : 


routine2 SStackDesc; 
stack2 [500] BYTE; 

REENTRANT function () a u$Param := 
{ 

$coSave() ; 

$coRestore(&routine2); 

RESULT := NIL; 

} ; 
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$SWITCH 


Example of the $SWITCH CUF 

The following program segment demonstrates a two 
coroutine program. The first coroutine (bold faced 
lines) is created by the $coInit function call [1] and falls 
asleep after creating a second coroutine by $coFork [2]. 

The second coroutine (italicized lines) begins after the 
call to $coFork [3] and continues until the call to $coSwitch 
[4]. The $coSwitch returns execution control to the first 
coroutine which resumes as though it was returning from 
the function [5]. Note that the line [6] following the 
$coSwitch is never executed. 




TYPDEF u$Param BYTE; 

routinel SStackDesc; 
stackl [500] BYTE; 

V* 


REENTRANT function () a u$Param := 

{ 

function0(); 

$coFork(&routine2, &stack2[0], SIZEOF stack2); 
functionl(); 
function2(); 

$coSwitch(&routinel, NIL); 
function3() ; 

} ; 

ENTRY MAIN () := 

VAR pB a u$Param; 

{ 

$coInit(&routinel, &stackl[0], SIZEOF stackl); [1] 
pB := function(); 

function4() ; [5] 

function5(); 

} ; 


[ 2 ] 

13] 

14 ] 
[ 6 ] 


routine2 SStackDesc; 
stack2 [500] BYTE; 


9-12 


DAS L USER’S GUIDE 


50807-01 



$SCHED 


Introduction 

The $SCHED CUF is a set of functions that enables multiple 
threads to coexist within one RMS task. 


$SCHED definition file 

The $SCHED definition file must be included after the 
$LINKS and $STRING definition files. 

Note : The $SCHED definition file includes the $SWITCH 
definition file. 

Example : Your DASL include directives might look 
like this: 


INCLUDE(D$INC) 
INCLUDE(D$RMS) 
INCLUDE($STRING/DEFS) 
INCLUDE($LINKS/DEFS) 
INCLUDE($SCHED/DEFS) 


: (rest of the program) 
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$SCHED 


Overview of the $SCHED documentation 

This table contains an overview of the $SCHED 
documentation. 


To learn more about ... 

see page... 

scheduler terminology 

9-15 

scheduler properties 

9-16 

scheduler initialization and control 

9-17 

scheduler synchronization and message 
passing 

9-30 

scheduler tickling 

9-40 

scheduler logging 

9-43 

scheduler termination 

9-49 
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$SCHED 


Scheduler terminology 

$SCHED contains terminology that you may not be familiar 
with. Here is a rundown of a few of the terms used: 

• thread - A thread is a separate process running within a 
single RMS task. A thread can be in one of three states: 

• active (there is only one active thread at one time), 

• waiting to become active, or 

• waiting for a signal or a message from another thread. 

• execution control - Execution control refers to the 
period of time when a thread is actually running as the 
RMS task. 

• ready queue - The ready queue is a queue for threads 
which are ready to execute but are waiting to be 
scheduled. 

• semaphore - A semaphore is a communications device 
that is used to synchronize one thread with another. 

• message - A message is data that is transferred between 
threads and is synchronized by a semaphore. 

• feather - A feather is a variable that can be used to 
transfer information to threads. Feathers are primarily 
useful for informing threads that they should abort 
processing or stop waiting for a signal or a message. 

• tickle - Tickle refers to the sending of a feather to a 
thread. 
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Scheduler properties 

$SCHED has several properties that will help you to 

understand this scheduler: 

• run to completion - Each thread initiated in the 
scheduler executes to completion unless it gives up 
execution control. In other words, a thread runs without 
being interrupted by the scheduler. It is the 
responsibility of each thread to give up execution 
control to the scheduler if other threads are expected to 
execute. 

• prioritized - Each thread has a priority that is specified 
at the time of creation. The scheduler schedules higher 
priority threads to execute before lower priority 
threads. 

• first come , first serve - Within each priority, waiting 
threads are allowed to execute in a first come, first 
serve basis. 


$SCHED 


Scheduler initialization and control 

This section describes the variables, types, and functions 
that are provided for scheduler initialization and control. 

Use the following table to select a $SCHED constant, type, 
variable, or function. 


If you want to. . . 

then see.. . 

page 

determine the maximum priority 

SmaxPriority. 

9-18 

declare a priority for a thread 



define the private data descriptor 

u$SchedData. 

9-19 

declare a thread control block 
descriptor 

SThreadCtlBlk. 

9-20 

use the current thread control 
block 

ScurTCB. 

9-21 

declare a thread entry point 

SThread. 

9-21 

initialize the program to be a 
thread 

SinitSched. 

9-22 

start a new thread 

$fork. 


determine if there are threads 
waiting to be scheduled 

SwouldPass. 

9-25 

pass execution control to any 
waiting threads 

$pass. 

9-26 

define a function that will 
execute before a scheduled thread 

u$threadln. 

■ 

define a function that will 
execute after a scheduled thread 

u$threadOut. 

9-28 

release thread control block 
memory 

u$relTcb. 

9-29 
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$SCHED 


$maxPriority constant 


$maxPriority is defined as a constant and is available for 
you to use. 


Constant Definition 

Description 

DEFINE($maxPriority, 7) 

Maximum priority of a thread. 


$Priority type 

$ Priority is defined as follows: 


Type Definition 

Description 

TYPDEF SPriority BYTE; 

The priority of the thread. It 
is used by the scheduler to 
determine the order to execute 
the threads. 0 is the lowest 
priority, SmaxPriority is the 
highest. 
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u$SchedData type 

The u$SchedData type is a type that must be defined by 
you. Variables of this type may be used to store 
information that is unique to individual threads. 

Example : This example uses u$SchedData to keep 
information about NOSL streams which are unique to each 
thread. Any commonly used function that needs to do any 
NOSL I/O can use this information without knowing which 
thread it is processing. 


TYPDEF u$SchedData STRUCT { 
stream n$Stream; 
ptr a BYTE; 
len BYTE; 

}; 
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$ThreadCtlBlk type 

The $ThreadCtlBlk type is needed to define variables used 
by the $SCHED functions. All fields, except privData, do 
not need to be set or examined by your program. 

$ThreadCtlBlk is defined as follows: 


Type Definition 

Description 

TYPDEF SThreadCtlBlk STRUCT { 
link SListHeader; 

A link that is used to 
place this thread control 
block on a queue. 

msg a $Message; 

Points to any message 
that has been received. 

privData a u$SchedData; 

Points to data that is 
initialized and used by 
you. 

pending a $Sema4; 

Points to the semaphore 
this thread is waiting 
on. NIL if the thread is 
not waiting. 

feather a u$Feather; 

Points to the data passed 
into the thread if it has 
been tickled. 

priority $Priority; 

Priority of this thread. 

stack $StackDesc; 

Describes the stack for 
this thread. 

stackData [$stackSize] BYTE; 

Storage area for the 
recursive stack. 

name SString; 

} ; 

Name used for logging 
scheduler events. 


9-20 


DASL USER'S GUIDE 


50807-01 



$SCHED 


ScurTCB variable 

$curTCB is declared as part of the $SCHED CUF and is 
available for you to examine. 


Variable Definition 

Description 

ScurTCB a SThreadCtlBlk; 

Pointer to the currently 
active thread control block. 


$Thread type 

Use the $ Thread type to declare functions that are entry 
points of new threads. 

$Thread is defined as follows: 


Type Definition 

Description 

TYPDEF SThread ( 

feather a u$Feather 

); 

Address of a feather. Will 
indicate whether a tickle 
occurred sometime between when 
this function was placed on the 
ready queue and when it actually 
began executing. NIL if no 
tickle occurred. 


Example : 


function $Thread ;= 

{ 
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$initSched function 

$initSched initializes the running program to be a 
scheduled thread. $curTCB is left pointing at the thread 
control block that describes this thread. 

Note : This function must be called prior to all other calls to 
the scheduler. It should also be called prior to any calls to 
REENTRANT or RECURSIVE functions. 


Function Syntax 

Input 

Output 

SinitSched ( 

priority $Priority, 

name a SString 

); 

Priority of this thread. 
Note: Valid inputs are 

0 to SmaxPriority. 


Address of the name for 
this thread which will 
be used for scheduler 
logging. 



Example : 


function () := 

VAR STATIC name $String := $str('Main Thread'); 
{ 

$initSched(1, &name); 
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$fork function 

$fork starts up a new thread. The new thread is placed at 
the end of the ready queue where it begins execution once 
the current thread, threads with higher priorities, and 
threads with equal priority that were already on the ready 
queue yield execution control. 


Function Syntax 

Input 

Output 

$fork ( 

fp a SThread, 

Address of the 
function to 
begin executing 
as the new 
thread. 


newTCB a $ThreadCtlBlk, 

Address of a 
thread control 
block. 

Note: The 

Initialized 
thread control 
block with 
information 


privData field 
should be 
initialized. 

about the new 
thread. 

priority $Priority, 

Priority of the 
this thread. 

Note: Valid 


! 

inputs are 0 to 
SmaxPriority. 


name a $String 

i 

! 

>• 

Address of the 
name for this 
thread which 
will be used 
for scheduler- 
logging. 



Chapter 9. SCHEDULER CUFS 


9-23 




$SCHED 


$fork function (continued) 
Example : 


TYPDEF u$SchedData STRUCT { 
stream n$Stream; 
ptr a BYTE; 
len BYTE; 

} ; 

threadOne $Thread := 

{ 

(DASL code) 


function () := 

VAR tcbl $ThreadCtlBlk; 

privData u$SchedData; 
string [80] CHAR; 

STATIC name $String := $str('Thread One'); 

{ 

tcbl.privData := &privData; 
tcbl.privDataA.stream ;= n$WSOut; 
tcbl.privDataA.ptr := string[0] ; 
tcbl.privDataA.len := SIZEOF string; 
$fork(&threadOne, &tcbl, 1, &name); 
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SwouldPass function 

$wouldPass determines if there are threads waiting to be 
scheduled at or above the same priority on the ready 
queue. 


Function Syntax 

Input 

Output 

SwouldPass ( 

) BOOLEAN; 


TRUE if there are threads ready 
to be scheduled. FALSE 
otherwise. 


Example : 


function () := 

{ 

IF ~ $wouldPass() THEN 

display('No threads on the ready queue.'); 
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$pass function 

$pass causes the active thread to give up execution control 
to any threads on the ready queue with higher or equal 
priority. If no such threads exist, the current thread 
resumes execution control. 


Function Syntax 

Input 

Output 

Spass ( 

) a u$Feather; 


Returns the address of a 
feather if this thread was 
tickled while asleep. NIL if 
not tickled. 


Example : 


function () := 

{ 

IF $pass() ~= NIL THEN 

display('I was tickled awake.') 

ELSE display('The scheduler awakened me.'); 
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u$threadln function 

u$threadln is a function that must be declared by you. It 
is called right after a thread is scheduled and may be 
written for any purpose. 

Note : u$threadln must be declared ’’ENTRY". 

The scheduler expects a function with the following 
syntax: 


Function Syntax 

Input 

Output 

u$threadln ( 

); 




Example : The following program segment is the minimum 
u$threadln. This is a perfectly acceptable definition for 
this function. 


ENTRY u$threadIn := 

{ 

}; 
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u$threadOut function 

u$threadOut is a function that must be declared by you. It 
is called right before a thread is unscheduled and may be 
written for any purpose. 

Note : u$threadOut must be declared ’’ENTRY". 

The scheduler expects a function with the following 
syntax: 


Function Syntax 

Input 

Output 

u$threadOut ( 

); 




Example : The following program segment is the minimum 
u$threadOut. This is a perfectly acceptable definition for 
this function. 


ENTRY u$threadOut ;= 
{ 

} ; 
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u$relTcb function 

u$relTcb is a function that must be declared by you. It 
should release the memory used by the thread control 
block which is pointed to by $curTCB. 

Note: u$relTcb must be declared ’’ENTRY”. 


The scheduler expects a function with the following 
syntax: 


Function Syntax 

Input 

Output 

u$relTcb ( 

); 




Example : The following program segment uses the $ BUDDY 
CUF to deallocate the memory used by the thread control 
block. 


ENTRY u$relTcb ;= 

{ 

$free($curTCB, SIZEOF $curTCBA); 
}; 
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Scheduler synchronization and message passing ( 

Semaphores and messages are used to synchronize and 
transfer information between threads. 


Types and functions 

This section describes the types and functions provided for 
scheduler synchronization and message passing. 

Use the following table to select a $SCHED type or 
function. 


If you want to... 

then see... 

page 

declare a semaphore descriptor 

$Sema4. 

9-31 

declare a message descriptor 

SMessage. 

9-32 

initialize a semaphore 

$initSema4. 

9-33 

signal a semaphore 

Ssignal. 

9-34 

wait for a semaphore 

SwaitOn. 

9-35 

send a message 

SsendMsg. 

9-37 

wait for a message 

SwaitMsg. 

9-38 


9-30 


DAS L USER'S GUIDE 


50807-01 





$SCHED 


$Sema4 type 

The $Sema4 type is needed to define variables used by the 
$SCHED functions. The contents, however, do not need to 
be set or examined by your program. 

$Sema4 is defined as follows: 


Type Definition 

Description 

TYPDEF $Serna4 STRUCT { 


count INT; 

A counter used to synchronize 
threads. 

link SListHeader; 

A link used to queue threads 
that are waiting for this 
semaphore to be signaled. 

name SString; 

A name that is used for logging 

} ; 

scheduler events. 
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$Message type 

$ Message is defined as follows: 


Type Definition 

Description 

TYPDEF SMessage STRUCT { 


link $ListHeader; 

A link that is used to save 
this message for a thread. 

Note: This field will be 
maintained by the scheduler. 

name SString; 

A name that will be used for 
logging scheduler events. 

Note: This field must be 

1 ; 

initialized by your program. 


In order to pass messages between threads, a field of type 
$ Message should be declared as the first member in a 
structure which contains the elements of your message. 

Example : If you need to pass an array of 10 characters 
between threads, your message type might look like this: 


TYPDEF Message STRUCT { 
msgCtl $Message; 
msgStr [10] CHAR; 

} ; 
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$initSema4 function 

$initSema4 initializes a semaphore so that it can be used by 
the scheduler. 


Function Syntax 

Input 

Output 

$initSema4 ( 
ptr a $Sema4, 

Address of 
semaphore to 
initialize. 

Initialized 
semaphore. 

name a SString 

); 

Address of a name 
for this semaphore 
which will be used 
for scheduler 
logging. 



Example : 


function () := 

VAR sema4 $Sema4; 

STATIC name $String := $str('Semaphore 1'); 

{ 

$initSema4-(&sema4, &name); 
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$signal function 

$signal uses a semaphore to let another thread know that a 
certain event has taken place. If a thread has been waiting 
for this signal, $signal places it onto the ready queue. 
Otherwise, the signal is saved so a thread will know this 
event has taken place. 


Function Syntax 

Input 

Output 

$signal ( 

ptr a $Sema4 

); 

Address of the semaphore to 
signal. 



Example : 


sema4 $Sema4; 

function () := 

{ 

$signal(&sema4-); 
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SwaitOn function 

$waitOn checks to see if a semaphore has been signaled 
to determine if a certain event has taken place in another 
thread. If the semaphore has been signaled, the thread 
continues to execute. Otherwise, the thread gives up 
execution control and waits for a signal. 


Function Syntax 

Input 

Output 

SwaitOn ( 

ptr a $Sema4, 

completed a BOOLEAN 

) a u$Feather; 

Address of the 
semaphore to 
wait on. 


Address of a 
boolean. 

TRUE if the 
semaphore you 
were waiting on 
was signaled. 
FALSE if tickled 
before receiving 
the message. 

Note: This flag 
can be TRUE even 
if the thread 
was tickled. 


Returns the 
address of a 
feather if this 
thread was 
tickled while 
asleep. NIL if 
not tickled. 
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SwaitOn function (continued) 
Example : 


sema4 $Sema4; 

function () := 

VAR completed BOOLEAN; 

feather a u$Feather; 

{ 

feather ;= $waitOn(&sema4-, &completed); 

IF feather ~= NIL THEN 

display('I was tickled awake.’); 

IF completed THEN 

display(’I received the signal.') 

ELSE display('I did not receive the signal.'); 

} ; 
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SsendMsg function 

$sendMsg uses a semaphore to let another thread know 
that a message has been sent to it. If a thread has been 
waiting for this message, $sendMsg places the thread onto 
the ready queue. Otherwise, the message is saved so a 
thread will know this message has been sent. 


Function Syntax 

Input 

Output 

SsendMsg ( 



ptr a $Sema4, 

Address of the semaphore to 



signal. 


msg a SMessage 

Address of the message to 


); 

send. 



Example : 


TYPDEF Message STRUCT { 
msgCtl SMessage; 
msgStr [10] CHAR; 

1 ; 

message Message; 
sema4 $Sema4; 
function () := 

VAR STATIC name $String := $str('Message 1'); 

{ 

n$read(n$WSIn, ^message.msgStr[0], 10); 
message.msgCtl.name := name; 

$sendMsg(&sema4-, &message . msgCtl) ; 
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SwaitMsg function 

$waitMsg checks to see if a semaphore has been signaled 
to determine if a certain message has been sent by another 
thread. If the semaphore has been signaled, the thread 
receives the message and continues to execute. 

Otherwise, the thread gives up execution control and waits 
for the message. 


Function Syntax 

Input 

Output 

SwaitMsg ( 

ptr a $Sema4, 

msgPtr aa SMessage 

Address of the 
semaphore to 
wait on. 


Address of a 
pointer to a 
message. 

Points to the 
message sent by 
the sending 
thread. NIL if 
tickled before 
receiving the 
message. 

Note: This pointer 

) a u$Feather; 


can point to a 
message even if 
the thread was 
tickled. 


Returns the 
address of a 
feather if this 
thread was tickled 
while asleep. NIL 
if not tickled. 
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$waitMsg function (continued) 
Example : 


TYPDEF Message STRUCT { 
msgCtl $Message; 
msgPtr a [80] CHAR; 

} ; 

message Message; 

sema4 $Sema4; 

function () := 

VAR mPtr a $Message; 

feather a u$Feather; 

{ 

feather := $waitMsg(&sema4-, &mPtr); 

IF feather ~= NIL THEN 

display('I was tickled awake.'); 

IF mPtr ~= NIL THEN 

display((<AMessage>mPtr>A.msgStr) 

ELSE display('I did not receive the message.'); 
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Scheduler tickling 

Tickling refers to the sending of a feather to a thread. 
Tickling is primarily useful for informing threads that they 
should abort processing or stop waiting for a signal or a 
message. 


Types and functions 

This section describes the types and functions provided for 
scheduler tickling. 

Use the following table to select a $SCHED type or 
function. 


If you want to.. . 

then see... 

page 

define the feather descriptor 

u$Feather. 

9-41 

pass a feather to a thread 

Stickle. 

9-42 
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u$Feather type 

The u$ Feather type is a type that must be defined by you. 
Variables of this type can be used to transfer information 
to threads such as "terminate processing" or "stop waiting 
for a signal". 

Note : By convention, a thread should terminate itself if it 
receives a feather pointer that equals $NOADR. 

Example : This example defines u$Feather to be a byte. 
Since a byte has 256 possible representations (0 to 255), a 
feather of this type could represent 256 different messages 
when passed into a thread. 


I TYPDEF u$Feather BYTE; 
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Stickle function 

$tickle passes a feather to a thread. If the thread is waiting 
for a signal or a message, it stops waiting and is placed on 
the ready queue. By convention, a thread should terminate 
itself if it receives a feather pointer that equals $NOADR. 

Note : If the thread is tickled twice before it obtains 
execution control, the first feather will be lost. 


Function Syntax 

Input 

Output 

Stickle ( 

tcb a $ThreadCtlBlk, 

Address of the 
thread control 
block to 
tickle. 

Thread control 
block feather 
field set. 

feather a u$Feather 

); 

Address of the 
feather to 
tickle the 
thread with. 



Example : 


killFeather a u$Feather := $N0ADR; 

function () := 

{ 

$tickle(tcbl, killFeather); 
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Scheduler logging 

Events in the scheduler can be traced by an optional logging 
facility. If logging is active, each event in the scheduler 
calls the logging function at the beginning and ending of the 
scheduler event. Three exceptions are $signal, $sendMsg, 
and $ tickle which only log the beginning of the event. 


Variables, types, constants, and functions 

This section describes the variables, types, constants, and 
functions provided for scheduler logging. 

Use the following table to select a $SCHED variable, type, 
constant, or function. 


If you want to... 

then see... 

page 

turn logging on or off 

u$eventLoggingOn. 

9-44 

determine the types of 
scheduler events logged 

$EventType. 

9-45 

use the mask that signifies 
the end of an event 

SresultOfEvent. 

9-46 

define the function to log 
events 

u$eventLog. 

9-47 
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u$eventLoggingOn variable 

u$eventLoggingOn is a boolean variable that must be 
declared by you. It is used to determine whether or not to 
log the events of the scheduler. 

Note : u$eventLoggingOn must be declared "ENTRY". 

Example : 


ENTRY u$eventLoggingOn BOOLEAN := TRUE; 
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$EventType type 

$EventType contains the values of all of the possible 
events to be logged by the scheduler. 

$EventType is defined as follows: 


Type Definition 

Description 

TYPDEF SEventType ENUM ( 
$eventInitSema4, 

Initializing a semaphore 

SeventFork, 

Creating a new thread. 

$eventPass, 

Thread is giving up execution 
control. 

SeventSwitch, 

Scheduling the next thread. 

SeventSignal, 

Signaling a semaphore. 

SeventWaitOn, 

Waiting on a semaphore. 

SeventSendMsg, 

Sending a message. 

$eventWaitMsg, 

Waiting on a message. 

$eventTickle 

); 

Tickling a thread. 
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SresultOfEvent constant 

$resultOfEvent is defined as a constant and is available for 
you to use. 


Constant Definition 

Description 

DEFINE($resultOfEvent, 0x80) 

Bit mask that is "or"ed 
with the $eventTypes 
logged at the end of an 
event. This distinguishes 
the ending log of an event 
from the beginning log. 


Example : 


ENTRY u$eventLog /* (event SeventType, 
al, a2 a $String, 
feather a u$feather) */ := 

{ 

IF event && $resultOfEvent THEN 

n$format(logStream, 'Event end', LN); 
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u$eventLog function 

u$eventLog is a function that must be declared by you if 
u$eventLoggingOn is TRUE. It should log the events of the 
scheduler. 


Note : u$eventLog must be declared "ENTRY”. 


Function Syntax 

Input 

Output 

u$eventLog ( 

event SEventType, 

Scheduler event. 


al a SString, 

Address of a string. See 
table on next page. 


a2 a SString, 

Address of a string. See 
table on next page. 


feather a u$Feather 

); 

Address of a feather. 

See table on next page. 



Example : 


ENTRY u$eventLog /* (event $eventType, 
al, a2 a $String, 
feather a u$feather) */ := 

{ 

IF event &<& $resultOfEvent THEN 

n$format(logStream, 'Event end.', LN); 
event &&= ~~ $resultOfEvent; 
n$format(logStream, S(events[event 1), 

' ’, S(alA.ptrA, alA.len)); 

IF a2 ~= NIL THEN 

n$format(logStream, ' ', S(a2A.ptrA, a2A.len)); 
n$format(logStream, LN) ; 

}; 
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u$eventLog function (continued) 

u$eventLog can expect the following input parameters 
based upon the events listed on the left side of the table: 


Event 

a 1a 

s2a 

feather a 

InitSema4 

Semaphore 
name. 

NIL 

NIL 

Fork 

Current thread 
control block 

name. 

New thread 

name. 

NIL on entry. 
Current 
feather on 
exit. 

Pass 


NIL 

NIL on entry. 
Feather if 
tickled on 
exit. 

Switch 



NIL on entry. 
Current 
feather on 
exit. 

Signal 

Semaphore 
name. 


NIL 

WaitOn 



NIL on entry. 
Feather if 
tickled on 
exit. 

SendMsg 


Message name. 

NIL 

WaitMsg 


NIL on entry. 
Message name 
on exit. 

NIL on entry. 
Feather if 
tickled on 
exit. 

Tickle 

Thread 

control block 
name to 

tickle. 

NIL 

Feather to 
tickle with. 
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Scheduler termination 

The threads running under the scheduler are terminated if 

• the program ends normally by exiting the MAIN 
function, or 

• an end RMS task is issued such as $ERROR or $EXIT. 


9 . 
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Introduction 

The $RMSIDLE CUF is the operating system dependent part 
of the scheduler that includes 

• functions that enable a thread to go to sleep while 
waiting for an RMS I/O to complete, and 

• an idle thread which wakes up threads after their I/O has 
completed. 


$RMSIDLE definition file 

The $RMSIDLE definition file must be included after the 
$LINKS and $STRING definition files. 

Note : The $RMSIDLE definition file includes the $SCHED 
definition file. 

Example : Your DASL include directives might look 
like this: 


INCLUDE(DSINC) 
INCLUDE(D$RMS) 
INCLUDE($STRING/DEFS) 
INCLUDE($LINKS/DEFS) 
INCLUDE($RMSIDLE/DEFS) 


: (rest of the program) 
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$RMSIDLE types and functions 

Use the following table to select a $RMSIDLE type or 
function. 


If you want to... 

then see ... 

page 

declare a file access variable 
descriptor 

$FavId. 

9-51 

start the idle thread 

SinitRmsIdle. 

9-52 

wait for I/O to complete 

SwaitSinglelO. 

9-53 

give up execution control if 
there are any waiting threads 

Syield. 

9-55 

declare a function to handle 
scheduler deadlock 

u$deadLock. 

9-56 

obtain finer control over I/O 
scheduling 

SRMSIDLE low 
level 

functions. 

9-57 


$Favld type 


$FavId is defined as follows: 


Type Definition 

Description 

TYPDEF SFavId UNSIGNED; 

File access variable ID that 
identifies a file to a thread. 
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$initRmsldle function 

$initRmsIdle starts up a 0 priority idle thread on the 
scheduler. 

Note : $initRmsIdle should be called right after $initSched is 
called. 


Function Syntax 

Input 

Output 

SinitRmsIdle ( 

privData a u$SchedData 

); 

Address of any 
information that may 
be unique to this 
individual thread. 



Example : 


function () := 

VAR STATIC name $String := $str('Main Thread'); 

{ 

$initSched(1, &name); 

$initRmsIdle(NIL); 
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SwaitSinglelO function 

$waitSingleIO informs the idle thread of a pending I/O and 
causes the current thread to give up execution control 
while waiting for a specific file I/O to complete. 


Function Syntax 

Input 

Output 

$waitSingleIO ( 
favld $FavId, 

File access 
variable ID of 
the file with 
the pending I/O. 


name a $String, 

Address of a 
name to be used 
as the name of 
the semaphore to 
wait on. 


completed a BOOLEAN, 

Address of a 
boolean. 

TRUE if the 
pending I/O 
completed. FALSE 
if tickled 
before the I/O 
completed. 

Note: May be 

TRUE even if the 
thread was 
tickled. 

errCode a $ERRCODE 

Address of a 
$ERRCODE. 

Error code if 
$SECWAIT error. 
SCODE field is 0 
if no error. 

) a u$Feather; 


Returns the 
address of a 
feather if this 
thread was 
tickled while 
asleep. 
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$RMS!DLE 


SwaitSinglelO function (continued) 
Example : 


function (pfdb a $PFDB) := 

VAR feather a u$Feather; 

STATIC name SString := $str('Readl') ; 
completed BOOLEAN; 
errCode SERRCODE; 

{ 

IF $SECR(pfdb, FALSE) && D$CFLAG THEN $ERMSG() ; 

feather := $waitSingleIO(pfdbA.$PFVID, 

&name, 

&completed, 

SterrCode ); 

IF feather ~= NIL THEN 

display('I was tickled awake.'); 

IF completed THEN { 

display('The I/O completed.'); 
checkForIOError(&errCode); 

} ; 
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$RMSIDLE 


$yield function 

$yield causes the thread to give up execution control if 
there are any threads with higher or equal priorities ready 
to execute. Otherwise, any threads that were waiting on an 
I/O are checked to see if their I/O completed. If so, the 
first thread found is placed on the ready queue and obtains 
execution control if it has a higher or equal priority 
than the current thread. 


Function Syntax 

Input 

Output 

Syield ( 

) a u$Feather; 


Returns the address of a 
feather if this thread was 
tickled while asleep. NIL if 
not tickled. 


Example : 


function () := 

{ 

IF $yield() ~= NIL THEN 

display('I was tickled awake.') 

ELSE display('The scheduler awakened me.'); 
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$RMSIDLE 


u$deadLock function 

u$deadLock is a function that must be declared by you. It 
is called if the idle thread obtains execution control and 
finds 

• no threads waiting for an I/O, or 

• an I/O that was issued without informing the idle thread 
by calling $waitSingleIO or $doneIO. 

Note : This function must be declared "ENTRY” and should 
not return to the calling function. 


Function Syntax 

Input 

Output 

u$deadLock ( 
favld $FavId 

); 

NIL if there are no threads 
waiting on an I/O. Otherwise, a 
file access variable ID of a 
file that has a pending I/O 
that the idle thread was not 
aware of. 



Example : 


ENTRY u$deadLock /* (favld $FavId) */ := 

{ 

IF favld = NIL THEN display('Scheduler Deadlock') 
ELSE n$format(n$WSOut, ’Unknown FAV ', D(favld)); 
$ERROR(); 

}; 
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$RMSIDLE 


$RMSIDLE low level functions 

The functions $doneIO, $waitIO, $checkIO, and $stopIO are 
all low level functions that are called by the $RMSIDLE 
functions described on the previous pages. In most cases, 
these functions, along with the $IOMsg type, can be ignored 
unless finer control is needed. 


Low level $RMSIDLE types and functions 

Use the following table to select a $RMSIDLE type or 
function. 


If you want to. . . 

then see... 

page 

declare an I/O message descriptor 

SIOMsg. 

9-58 

inform the scheduler of an I/O 

$doneIO. 

9-59 

wait for an I/O to complete 

SwaitlO. 

9-60 

check for completed I/Os 

SchecklO. 

9-62 

terminate an I/O request 

SstopIO. 

9-63 
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$RMSIDLE 


$IOMsg type 

$IOMsg is defined as follows: 


Type Definition 

Description 

TYPDEF $IOMsg STRUCT { 


msg $Message; 

Message used to describe this 
pending I/O. 

compIO a $Sema4; 

Semaphore to signal once the 

I/O has completed. 

favld $FavId; 

File access variable ID of the 
file with the pending I/O. 

errCode $ERRCODE; 

1; 

Resulting $SECWAIT error if an 

I/O error occurred. 
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$RMSIDLE 


$donelO function 

$doneIO informs the idle thread that an I/O has been done. 


Function Syntax 

Input 

Output 

SdonelO ( 

msg a $IOMsg 

); 

Initialized I/O message. The 
message name field, the compIO 
field, and the favld field must 
be initialized. 



Example : 


function (pfdb a $PFDB) := 

VAR message $IOMsg; 

STATIC name $String := $str('ReadI') ; 
compIO $Sema4; 

{ 

IF $SECR(pfdb, FALSE) && D$CFLAG THEN $ERMSG() ; 
message.msg.name := name; 
message.compIO ;= &compIO; 
message.favid := pfdbA.$PFVID; 

$doneIO(&message); 
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$RMSIDLE 


SwaitIO function 

$waitIO causes the thread to give up execution control 
until the I/O announced by the $doneIO completes. 


Function Syntax 

Input 

Output 

SwaitIO ( 



compIO a $Sema4, 

Address of the 
semaphore to 
wait on. 


msgPtr aa $IOMsg 

Address of a 

Points to the I/O 


pointer to an 

message sent by 


I/0 message. 

the sending 
thread. NIL if 
tickled before 
receiving the 
message. 

Note: This pointer 
can point to a 
message even if 
the thread was 
tickled. 

) a u$Feather; 

i 

Returns the 
address of a 
feather if this 
thread was tickled 
while asleep. NIL 
if not tickled. 
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$RMSIDLE 


$waitlO function (continued) 
Example : 


function (pfdb a $PFDB) := 

VAR message $IOMsg; 

STATIC name $String : = $str('Readl') ; 
compIO $Sema4; 
pMsg a $IOMsg; 

{ 

IF $SECR(pfdb, FALSE) && D$CFLAG THEN $ERMSG() ; 
message.msg.name := name; 
message.compIO := &compIO; 
message.favid := pfdbA.$PFVID; 

$doneIO(&message); 

$initSema4(&compIO, &name) ; 

IF $waitIO(&compIO, &pMsg) ~= NIL THEN 
display('I was tickled awake.'); 

IF pMsg ~= NIL THEN disp!ay('The I/O completed.') 
ELSE display('The I/O did not complete.'); 
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SchecklO function 

$checkIO checks to see if there are any threads that are 
waiting on an I/O to see if their I/O completed. If so, 
the first thread found is placed on the ready queue. 

Note : Unlike $yield, execution control is always retained. 


Function Syntax 

Input 

Output 

SchecklO ( 

) BOOLEAN; 


TRUE if a message was sent to a 
thread to verify a completed 

I/O. FALSE otherwise. 


Example : 


function () := 

{ 

IF $checkIO() THEN 

display('A thread completed an I/O.’); 
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$RMSIDLE 


$stoplO function 

$stopIO terminates an I/O request that a thread is currently 
waiting to complete. 

Note : A $waitIO must be issued to remove the waiting 
message from the pending I/O queue. 


Function Syntax 

Input 

Output 

SstopIO ( 

favld UNSIGNED 

File access 
variable ID of the 
file to stop the 
I/O. 


) BOOLEAN; 


TRUE if the I/O 
was stopped. 

FALSE if favld was 
not waiting on an 
I/O. 


Example : 


function (pfdb a $PFDB) := 

VAR pMsg a $IOMsg; 

{ 

IF $stopIO(pfdb a . $PFVID) THEN 

display(’I/0 was terminated.’); 
$waitIO(&compIO, &pMsg) ; 
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Chapter 10. 

MISCELLANEOUS CUFS 

OVERVIEW 


Description 


The miscellaneous CUFs are an assortment of CUFs that 
handle several programming problems that were not 
covered in the previous chapters. 


Selecting a CUF 

Use the following table to determine which miscellaneous 
CUFs are available. 


If you want to.. . 

then use ... 

page 

examine RMS catalogs, subcatalogs, 
and related files 

$catWalk. 

10-2 

perform mathematical computations 
on points and rectangles 

$EUCLID. 

10-6 

parse tokens under D$I0 with a 
simple lexical scanner 

$LEXER. 

10-17 

pack or unpack environmental data 
into and from a character string 

$PATH. 

10-32 

generate a random number (byte) 

$RNDBYTE. 

10-36 
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ScatWalk 


Introduction 

The $catWalk CUF is a single function CUF which examines 
RMS catalogs, subcatalogs, and related files. 


ScatWalk types and functions 

Use the following table to select a $catWalk type or 
function. 


If you want to... 

then see ... 

page 

declare a function as an entry point 
for ScatWalk. 

SCatFunc. 

10-3 

examine a catalog 

ScatWalk. 
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ScatWalk 


$CatFunc type 

Use the $CatFunc type to declare functions that will be 
called by $cat\Valk with the information it obtains about the 
catalogs, subcatalogs, and files. 

$CatFunc is defined as follows: 


Type Definition 

Description 

TYPDEF SCatFunc ( 
env a $ENVT ( 

file a SFILEINFO 

); 

A pointer to an environment file 
entry table. 

A pointer to a file information 
structure. 


Example : 


function $CatFunc 

{ 
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$catWalk 


$catWalk function 

$catWalk opens a catalog file and calls a specified function 
with the result for each valid file in the catalog. 

Note : If the function called by $catWalk in turn calls 
$catWalk, the function must be declared RECURSIVE. 


Function Syntax 

Input 

Output 

ScatWalk ( 

openMode BYTE, 

Open mode to open the 
catalog file under. 
Example: $OMREAD 


env a $ENVT, 

Address of the 
environment entry 
table for the catalog 
file to examine. 


fileName a SNAMET, 

Address of the name of 
the catalog file to 
examine. 

Note: If the name is 
blank, the environment 
specified by envA will 
be used. Otherwise, 
filenameA must be a 
catalog under envA. 


func a $CatFunc 

Address of the 
function to be called 
by ScatWalk with the 
result. 

1 

Calls funcA with 
the environment 
entry table of 
the current 
catalog and the 
filename. 

) BOOLEAN; 


TRUE if ScatWalk 
completes with 
no errors. FALSE 
otherwise. 
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$catWalk 


$catWalk function (continued) 


Example : The following program displays all file and 
catalog names in the :W environment and all subcatalogs 
of the :W environment. 


INCLUDE(D$INC) 
INCLUDE(D$RMS) 
INCLUDE(D$RMSIO) 
INCLUDE(D$UFRENV) 
INCLUDE(N$/DEFS) 
INCLUDE($catWalk/DEFS) 


walk (env a $ENVT, file a $NAMET); 


RECURSIVE write $CatFunc := 

{ 

n$format(n$WSOut, S(fileA.$FILFNAM), 
S(f ileA. $FILFEXT), LN); 

IF f ileA. $FILFEXT = <$EXTT>” THEN 
walk(env, &file A .$FILFNAM); 

} ; 


RECURSIVE walk := 

{ 

IF ~ $catWalk($OMREAD, env, file, &write) 
THEN $ERMSG(); 

} ; 


ENTRY MAIN () := 

VAR env aa $ENVT; 

prior aa $ENVT; 

{ 

IF $ENVLOC(&<$ENVN>'W', &env, &prior) 
&& D$CFLAG THEN $ERMSG() ; 
walk(priorA, &<$NAMET>''); 

1 ; 
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$EUCLID 


Introduction 

The $ EUCLID CUF is a euclidean geometry package for 
performing mathematical computations on points and 
rectangles. 


$EUCLID functions, types, and constants 


Use the following table to select a $ EUCLID function, 
type, or constant. 


If you want to... 

then see... 

page 

determine the minimum of two scalars 

SMIN. 

10-7 

determine the maximum of two scalars 

$MAX. 

10-8 

declare a point descriptor 

SPOINT. 

10-9 

use one of the predefined points 

SEUCLID 
point 
constants. 

10-9 

add two points 

SPTADD. 

10-10 

subtract two points 

SPTSUB. 

10-11 

increment a point 

SPTINC. 

10-12 

decrement a point 

SPTDEC. 

10-13 

declare a rectangle descriptor 

SRECTANGLE. 

10-14 

determine an intersecting rectangle 

$ INTERSECT. 

10-15 

determine an enclosing rectangle 

$ENCLOSE. 

10-16 
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$EUCLID 


$MIN function 

$MIN determines the minimum of any two DASL scalars. 


Function Syntax 

Input 

Output 

$MIN ( 



numl Scalar, 

First value to be 
compared. 


num2 Scalar 

Second value to be 
compared. 


) Scalar; 


Minimum of the two 
values. 


Example : 


function (x, y INT) := 

{ 

n$format(n$WSOut, 'The minimum of x and y is ' , 
D( $MIN(x , y) ), LN); 


Chapter 10 


MISCELLANEOUS CUFS 


10-7 





$EUCLID 


$MAX function 

$MAX determines the maximum of any two DASL scalars. 


Function Syntax 

Input 

Output 

$MAX ( 



numl Scalar, 

First value to be 
compared. 


num2 Scalar 

Second value to be 
compared. 


) Scalar; 


Maximum of the two 
values. 


Example : 


function (x, y INT) := 

{ 

n$format(n$WSOut, ’The maximum of x and y is ', 
D( $MAX(x, y) ), LN); 
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$EUCLlD 


$POINT type 

$ POINT is defined as follows: 


Type Definition 

Description 

TYPDEF SPOINT STRUCT { 
x INT; 

y INT; 

} ; 

x axis coordinate. 

y axis coordinate. 


$EUCL!D point constants 


The following constants are declared as part of the 
$EUCLID CUF and are available for you to use. 


Constant Definition 

Description 

SPTZER0 SPOINT ;= {0, 0}; 

SPTONE SPOINT := (I, 1}; 

SPTTWO SPOINT := {2, 2}; 

Point with (0,0) coordinates. 

Point with (1,1) coordinates. 

Point with (2,2) coordinates. 
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SEUCLID 


$PTADD function 

$PTADD adds the x, y coordinates of one point to another, 
a := b + c; 


Function Syntax 

Input 

Output 

SPXADD ( 

a a SPOINT, 

Address of a 
point descriptor. 

Stores the result 
of the addition 
between bA and ca. 

b a SPOINT, 

Address of the 
first point to add. 


c a SPOINT 

Address of the 
second point to 
add. 


) a SPOINT; 


Pointer to the 
input variable a. 


Example : 


function (pPointl, pPoint2 a SPOINT) := 
VAR total $POINT; 

{ 

$PTADD(&total, pPointl, pPoint2); 
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$EUCLID 


$PTSUB function 

$PTSUB subtracts the x, y coordinates of one point from 
another, a : = b - c; 


Function Syntax 

Input 

Output 

SPTSUB ( 

a a $POINT, 

b a $P0INT, 

c a $POINT 

) a $POINT; 

Address of a 
point descriptor. 

Stores the result 
of the subtraction 
between bA and ca. 

Address of the 
first point to 
subtract. 


Address of the 
second point to 
subtract. 



Pointer to the 
input variable a. 


Example : 


function (pPointl, pPoint2 a $POINT) := 
VAR total $POINT; 

{ 

$PTSUB(&total, pPointl, pPoint2); 
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$EUCLID 


$PTINC function 

$PTINC increments the x, y coordinates of one point by 
another, a + = b; 


Function Syntax 

Input 

Output 

$PTINC ( 

a a $POINT, 

Address of the 
point to increment. 

Stores the result 
of the addition 
between aA and bA. 

b a SPOINT 

Address of the 
amount to increment 
the point by. 


) a SPOINT; 


Pointer to the 
input variable a. 


Example : 


\i 


function (pPointl, pPoint2 a $POINT) := 

{ 

$PTINC(pPointl, pPointZ); 
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$EUCLID 


$PTDEC function 

$PTDEC decrements the x, y coordinates of one point by 
another, a -= b; 


Function Syntax 

Input 

Output 

SPTDEC ( 

a a SPOINT, 

Address of the 
point to decrement. 

Stores the result 
of the subtraction 
between aA and bA. 

b a SPOINT 

Address of the 
amount to decrement 
the point by. 


) a SPOINT; 


Pointer to the 
input variable a. 


Example : 


function (pPointl, pPoint2 a SPOINT) := 

{ 

$PTDEC(pPointl, pPoint2); 
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$EUCLID 


$RECTANGLE type 

f 

$RECTANGLE is defined as follows: V 


Type Definition 

Description 

TYPDEF SRECTANGLE STRUCT { 


p $POINT; 

The bottom left x, y 
coordinate of the rectangle. 

size $P0INT; 

Length of the rectangle 

1; 

along the x and y axis. 


ft 
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$EUCLID 


$INTERSECT function 

$ INTERSECT determines if there is a common rectangle 
shared by two rectangles. 


Function Syntax 

Input 

Output 

$ INTERSECT ( 

a a SRECTANGLE, 

Address of a 
rectangle 
descriptor. 

Stores the values 
of the common 
rectangle between 
bA and ca. 

b a SRECTANGLE, 

Address of the 
first rectangle to 
check for an 
intersection. 


c a SRECTANGLE 

Address of the 
other rectangle to 
check for an 
intersection. 


) BOOLEAN; 


TRUE if there is 

a common 

rectangle. FALSE 
otherwise. 


Example : 


function (pRecl, pRec2 a SRECTANGLE) := 

VAR interRect $RECTANGLE; 

{ 

IF $INTERSECT(&interRect, pRecl, pRec2) THEN 
commonRectangle(&interRect); 
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$EUCLID 


$ENCLOSE function 

$ENCLOSE generates the coordinates for a rectangle that 
encloses two other rectangles. 


Function Syntax 

Input 

Output 

SENCLOSE ( 

a a SRECTANGLE, 

Address of a 
rectangle 
descriptor. 

Stores the values 
of the rectangle 
that encloses bA 
and ca. 

b a SRECTANGLE, 

Address of the 
first rectangle to 
enclose. 


c a SRECTANGLE 

); 

Address of the 
second rectangle 
to enclose. 



Example : 


function (pRecl, pRec2 a $RECTANGLE) := 
VAR encloseRect SRECTANGLE; 

{ 

$ENCLOSE(&encloseRect, pRecl, pRec2); 
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$LEXER 


Introduction 

The $ LEXER CUF is a simple token parsing or lexical 
scanning package that works under D$IO. 

Lexical scanners are most commonly used in compilers 
where certain characters or grouping of characters, called 
tokens, are expected in a certain arrangement. 


$LEXER definition file 

The $ LEXER definition file must be included after the 
$ STRING definition file. 

Example : Your DASL include directives might look 
like this: 


INCLUDE(D$INC) 
INCLUDE(D$RMS) 
INCLUDE($STRING/DEFS) 
INCLUDE($LEXER/DEFS) 


: (rest of the program) 
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$LEXER 


$LEXER types, variables, and functions 

Use the following table to select a $ LEXER type, variable, 
or function. 


If you want to... 

then see... 

page 

declare a character class 
descriptor 

SLexClass. 

10-19 

use a token type 

SLexType. 

10-20 

examine a SLEXER variable 

SLEXER 
variables. 

10-21 

initialize the character classes 

SlexClassInit. 

10-22 

reclassify a range of characters 

SlexClassify. 

10-23 

reclassify a string of 
characters 

SlexStrClassify. 

10-24 

initialize the lexical scanner 

Slexlnit. 

10-25 

get the next token 

SlexNext. 

10-26 

compare token with a string 

SlexEqual. 

10-27 

terminate if token ~= string 

SlexTaste. 

10-28 

get next token if token = string 

SlexEat. 

10-29 

get next token if token = string 
otherwise terminate 

SlexChew. 

10-30 

display error and terminate if 
fatal 

SlexError. 

10-31 
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$LEXER 


$LexClass type 

Every character the lexical scanner parses must be 
classified to be one of the seven lexical scanner character 
classes, $LexClass. 

$LexClass is defined as follows: 


Type Definition 

Description 

TYPDEF SLexClass ENUM ( 
SlexClassAlpha, 

Alphabetic characters. 

SlexClassDigit, 

Numeric characters. 

SlexClassSpace, 

Space and token division 
characters. 

SlexClassQuote, 

Quotation marks. 

SlexClassSyntax, 

Separators, delimiters, and 
other syntactic characters. 

SlexClassError, 

Invalid characters. 

SlexClassEnd 

); 

Lexical termination characters. 
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$LEXER 


$LexType type 

The character classes are used by the lexical scanner to 
identify the type of the current token. There are seven 
lexical scanner token types, $LexType. 

$LexType is defined as follows: 


Type Definition 

Description 

TYPDEF SLexType ENUM ( 
SlexTypeNil, 

No current token type. 

Note: This value is only used 
internally by the lexical 
scanner. 

SlexTypeld, 

The first character in the 
current token is a 

SlexClassAlpha. 

SlexTypeNum, 

The first character in the 
current token is a 

SlexClassDigit. 

SlexTypeStr, 

The current token is.contained 
within SlexClassQuotes. 

SlexTypeSyntax, 

The current single character 
token is a SlexClassSyntax. 

SlexTypeEnd 

); 

The current single character 
token is a SlexClassEnd. 
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$LEXER 


$LEXER variables 

The following variables are declared as part of the $ LEXER 
CUF and are available for you to examine. 


Variable Definition 

Description 

SlexLineNo UNSIGNED; 

Current input text file line 
number. 

SlexErrFlag BOOLEAN; 

TRUE if the lexical scanner error 
function, $lexError, has been 
called. FALSE otherwise. 

ScurLexType $LexType; 

Lexical scanner type of the 
current token. 

ScurLexVal $String; 

Current token. 

Note: This value is meaningful 
only if the token is contained on 
one line. 

ScurLexNum LONG; 

Numeric value of the token. 

Note: This value is meaningful 
only if the lexical scanner type 
of the current token is 

SlexTypeNum. 

ScurLexStr $String; 

String value of the token. 

Note: This value is meaningful 
only if the lexical scanner type 
of the current token is 

SlexTypeStr. 
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$LEXER 


SlexClassInit function 


SlexClassInit sets the character classifications to the 
predescribed default values. 


Function Syntax 

Input 

Output 

SlexClassInit ( 

); 




The default character classifications are : 


$LexClass Character 
Classifications 

Default 

Characters 

SlexClassAlpha 

A. .Z 

a. . z 

$ 

SlexClassDigit 

0. .9 

SlexClassSpace 

Space 

$LE0R 

SlexClassQuote 

tv 

SlexClassEnd 

$LE0F 

SlexClassError 

! 

All other 
characters 

SlexClassSyntax 

No defaults 
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$LEXER 


$lexClassify function 

$lexClassify reclassifies a range of characters. 

Note : This function should not be used to 

• reclassify $LEOR, $LEOF or the two quotation marks, or 

• classify any other characters as $lexClassQuote. 


Function Syntax 

Input 

Output 

SlexClassify ( 



from CHAR, 

Beginning character to 
reclassify. 


to CHAR, 

Ending character to 
reclassify. 


lexClass $LexClass 

); 

Character classification 
to assign to the 
characters. 



Example : 


function () := 

{ 

$lexClassInit() ; 

$lexClassify('a', ’z’, $lexClassError) ; 
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$LEXER 


SlexStrClassify function 

$lexStrClassify reclassifies all the characters in a string. 
Note : This function should not be used to 

• reclassify $LEOR, $LEOF or the two quotation marks, or 

• classify any other characters as $lexClassQuote. 


Function Syntax 

Input 

Output 

SlexStrClassify ( 

str [any size] CHAR, 

lexClass SLexClass 

); 

Any character string. 


Character 
classification to 
assign to the 
characters. 



Example : 


function () := 

{ 

$lexClassInit(); 

$lexStrClassify('+-*/', $lexClassSyntax); 
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$LEXER 


$lexlnit function 

$lexlnit initializes the lexical scanner with the input and 
error files and scans off the first token. 

Note : You must call $lexClassInit prior to calling this 
function. 


Function Syntax 

Input 

Output 

$lexlnit ( 



inFile a D$FILET, 

Pointer to an open D$IO 
text file to read. 


errFile a D$FILET 

Pointer to an open D$IO 


); 

text file to write. 



Example : 


function () := 

{ 

$lexClassInit() ; 

$lexlnit(&D$IN, &D$OUT); 
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$LEXER 


$lexNext function 

$lexNext obtains the next token from the input file. 


Function Syntax 

Input 

Output 

SlexNext ( 

) SLexType; 


The type of the token obtained 
from the input file. 


Example : 


function () := 

{ 

LOOP WHILE $lexNext() ~= $lexTypeId ; 
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$LEXER 


SlexEqual function 

$lexEqual compares a string to the current token for 
equality. 


Function Syntax 

Input 

Output 

SlexEqual ( 



str [any size] CHAR 

String to 
compare the 
current token 



against. 


) BOOLEAN; 


TRUE if the 
string and token 
are equal. FALSE 
otherwise. 


Example : 


function () := 

{ 

IF $lexNext() = SlexTypeld 

& $lexEqual( 'GOOD' ) THEN goodTokenQ; 


Chapter 10 


MISCELLANEOUS CUFS 


10-27 






$LEXER 


SlexTaste function 

$lexTaste terminates the program if a string and the 
current token do not match. 


Function Syntax 

Input 

Output 

SlexTaste ( 

str [any size] CHAR 

); 

String to compare the 
current token against. 



Example : 


function () := 

{ 

$lexTaste(’PASSWORD'); 
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$LEXER 


SlexEat function 

$lexEat obtains the next token if a string and the current 
token are equal. 


Function Syntax 

Input 

Output 

SlexEat ( 

str [any size] CHAR 

String to 
compare the 
current token 
against. 


) BOOLEAN; 


TRUE if the 
string and token 
are equal. FALSE 
otherwise. 


Example : 


function () := 

{ 

IF ~ $lexEat('PASSWORD') THEN 

$lexError('Password expected', TRUE); 
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$LEXER 


SlexChew function 

SlexChew terminates the program if a string is not equal to 
the current token. Otherwise, the next token is obtained. 


Function Syntax 

Input 

Output 

SlexChew ( 

str [any size] CHAR 

); 

String to compare the 
current token against. 



Example : 


function () := 

{ 

$lexChew('PASSWORD'); 
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$LEXER 


SlexError function 

$lexError displays an error message and terminates on 
fatal errors. 


Function Syntax 

Input 

Output 

SlexError ( 



str [any size] CHAR, 

Error message to 
display. 


fatal BOOLEAN 

Program terminates if 


); 

TRUE. 



Example : 


function () := 

{ 

IF ~ $lexEat('PASSWORD') THEN { 

$lexError(’Password expected’, TRUE); 
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$PATH 


Introduction 

The $PATH CUF packs and unpacks environment data 
strings that are used by the environment handling routines 
$ENVINS, $ENVLOC, $catWalk, etc... 


$PATH types and functions 

Use the following table to select a $PATH type or function. 


If you want to... 

then see . . . 

page 

declare an environment descriptor 

$Path. 

10-33 

pack environment data into a string 

SpathPack. 

10-34 

unpack environment data 

SpathUnPack. 

10-35 
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$PATH 


$Path type 


$Path is defined as follows: 


Type Definition 

Description 

TYPDEF $Path STRUCT { 


net SNAMET; 

Name of the ARC network 
for the environment. 

node SNAMET; 

Name of the node 
for the environment. 

res SNAMET; 

Name of the resource 
for the environment. 

hsi SHSI; 

Hierarchical structure 
information for the 
environment. 

Note: Information is in 
standard text format. 

nameExt SNAMEEXT; 

File name in the 
environment. 

Note: This field is not 
used by either packing 
or unpacking functions. 

nPass BYTE; 

Number of passwords 
for the environment. 

passwords [$MAXNPW] SPACKPW; 

Packed passwords 

1 ; 

for the environment. 
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$PATH 


SpathPack function 

$pathPack takes information in the environment path 
descriptor and packs it into an environment data string. 


Function Syntax 

Input 

Output 

SpathPack ( 



path a $Path, 

Address of the 
environment path 
descriptor to 
pack. 


envString a CHAR 

Address of a 

Initialized 


character in a 

environment data 

); 

character string. 

string. 


Example : 


function () := 

VAR p $Path; 

ptr a CHAR; 

STATIC password SUNPACKPW := ’PASSWORD'; 
envDataString [256] CHAR; 

{ 

p.net := 'GENESIS ' ; 

p.node := 'APDFPO '; 

p.res := 'APDO ’; 

p.hsi := 'UTILITY 

p.nPass := 1; 

IF $PAKPW(&password, &p.passwords[0], &ptr) 
&& D$CFLAG THEN $ERMSG(); 

$pathPack(&p, &envDataString[0]); 
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$PATH 


SpathUnPack function 

$pathUnPack takes information in the environment data 
string and unpacks it into a environment path descriptor. 


Function Syntax 

Input 

Output 

SpathUnPack ( 



envString a CHAR, 

Address of the 
the first 
character in the 
environment data 
string to unpack. 


path a $Path 

Address of an 

Initialized 


environment path 

environment path 

); 

descriptor. 

descriptor. 


Example : 


function (pEnv a CHAR) := 
VAR p $Path; 

{ 

$pathUnPack(pEnv, &p); 
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$RNDBYTE 


Introduction 

The D$RNDBYTE is a single function CUF that generates a 
random number (byte). 


D$RNDBYTE function 

D$RNDBYTE generates a random byte. 




Output 

D$RNDBYTE ( 

) BYTE; 


Generated random number. 

Note: The generator always 
starts from the same state. 


Example : 


function () := 

VAR rand BYTE; 

{ 

rand := D$RNDBYTE(); 
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